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“Re sorcerer will pay for itself many times over in saved time and effort.” 
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Bill Steinberg, author ofPyro! and PBTools 
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VIEWPOINT 


By Neil Tick! in. Publisher, Mac Tech Magazine 


Mac: OS X,*. Are We There Yet? 

I'm mi here today, having just received my copy of Mac OS X 
Ijcta. and I begin to wonder, as you probably are.., what's going 
to happen with this? When will developers make the jump to X? 
What does the future hold for us as developers? Now, while I 
won't profess to being a soothsayer, I’ll take the plunge and put 
my opinion in print for the world to see, 

Apple is Serious... Lhis time 

The developer community has been burned by Apple’s 
promise of a modern operating system since, say, the early to mid- 
1990’s* Yes, it lias been dial long. We've been through the original 
System 8 (not die one that shipped), Copland, rumors of die BeOS, 
Rhapsody, Yellow Box, and more. Time and Lime again, Apple has 
simply not delivered the promise of a “modern operating system 1 '. 
Some were technical problems, some were business problems.., 
and some were just plain old change in direction. 

So, why should we believe that this time Apple is going to 
make this happen? 

Two reasons: Steve jok and Public Beta, Sieve Jobs ain’t stand to 
lx. 1 publicly humiliated He's stexxt up saying, "the train lias left the 
station", and that (paraphrased) we’re moving forward with Mac OS X, 
not as a multi-prong strategy, but as a single strategy lor the future. Now, 
whether they ship Q1 2000 or Q2, l don't know... and it doesn't matter 
in the long am. Steve Jobs will make sure il ships in one form or another, 
relatively airly on next year. He jusi won’t stand for it king otherwise. 

How do we know that this isn't just some promise as we've heard 
before? A public beta. Not only does the general public have tangible 
evidence in its hands, but early remits arc* that it runs fairly well... a 
gtxxf indication dial were, in relative terms, dose. 

Of course, there’s always a third reason why tilings are different this 
time. Apple has moved into the arena of other, very profitable OS 
vendors... they are dunging for a kta! :) But seriously, you liave Lo 
klieve lliat tky will follow through this time since tliey are bold enough 
to charge for the beta. 

Yeah, Yfah,„ Fix Wait 

There are already a lot of developers moving lo X. But. some of you 
ate holding hack. This may k an important mistake, kit not for the 
reasons ilmt you are thinking. 

It's pretty dear that the Classic environment on Mac OH X (i.e., the 
environment responsible for running non-carf* mixed Mac OS 9 
applications) is going to work well. So, yes, your customers can run their 
Classic apps under X. 

The issue is that launching tire Classic environment tikes time... 
and frankly, even if il ran do Something about it. Apple has no incentive 
lo make it launch faster. Your customers will quickly learn that tliey want 
to avoid launching rite Classic environment if tliey have a choice. 

Tints where you come in... you can make their experience with 
your product a gtxxl one, or you can set yourself up for Uiem king 
disap]X)imed in the Classic situation and blaming your product. 


Bottom line; customers will want native and carbonized apps so 
tliey r can avoid Classic. Now Ls the lime to start working on it. 

Bor I Have So Much to Do! 

If you are like me, you have a million things to do, and not enough 
time to do them. Working on a new version of your application for an 
operating system tliat is technically not shipping, first hasn't bubbled up 
on the list. So, why should you move forward today? 

Fust, I'm not going Lo tell yuu what you should do with your 
project... tliafs your call to make. Only you have the information to 
make such a decision, though, ikre are a few li lings to consider. 

Anecdotally at least, carbonizing is relatively easy. For example, a 
typioal app could easily lake as little as 2 weeks to earlxmize to gel it up 
and running, A bit longer to iron the Issues out, and then of course 
testing. But, this is not a several month project, as ii may seem. 

More importantly, there are other benefits to carbonizing. 
Let me explain. 

lire tilings that slow folks down the most when eaitxmmng their 
apps typically are their own bugs. Many engineers are thrilled because 
(hey are re-writing I tad axle that they've wanted to gtl lo for a while, 
but haven't had time. 

Writing axle that Ls properly atrlxmized actually turns out to k a 
gcxxl way to debug and test your program — anti may result in lower 
QA or tech support costs. Mac OS X tells you n< >w that you are stepping 

on memory.not some day down the road when ycni aren't expecting 

it. In addition, the development and rid jugging turn around time is much 
faster than with Mac OS 9 — in put because, you aren’t generally 
crashing your system as you tracking down Ixigs. 

The bottom line Ls that caiixmizing your app is not the challenge or 
pan that people drink it is. It’s actually a lot easier and once through tile 
prcxress, people are generally happy they did it citing that it wasn’t as 
hard as iky thought it would be. 

Leading hie Market 

Look.,, Apple is going to push really, really hard here,., hard on 
their own engineers, and hard on develojx'rs, The timing of when they 
will ship LO will k dependent on two things: engineering anti market 
rcsjxmse. If the market responds saying that tliey want lots of things 
changed, then Apple will have lo do lJxj.se in addition to the other items 
they already know aknit. Rest assuied though... a 1,0 version of Mac OS 
X will ship sooner rather than later. 

Furthermore, the acceptance of X as the current (and only) 
operating system will dqxmd on market acceptance. I expect lo sec 
Apple pushing die timeline forward just ahead of the market. They'Ve got 
experience with this... just the way they dove in on USB, FireWire, and 
even Wireless Networking. Yes, il will he a bit painful to make such a 
leap, but in recent years, Apple has l^een able to keep that fxiin period 
relatively short (look at USB), 

Bottom line; Jobs Ls right... tiie train lias left the station. If you are 
going to support Mac OS X in a way that w ill help promote your pnxiuct, 
the time Ls now to carbonize, ES3 
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GETTING 
STARTED - 
NETWORKING 


By John C. Welch 


Networks 201 pt. 4 


Layer 2: The Data Link Layer 


Rmuisn 

Before we start with this month's 
installment of our look at networks, an 
apology/error fix. In the Iasi article, we staled 
that to find the wavelength of signal, you 
would invert the frequency, via the equation 
I/fret]. Unfortunately, that was incomri. Unit 
equation actually gives you the period of the 
signal. To get the wavelength, you would 
more correctly use the equation c/ffeq, where 
c represents the speed of light in meters per 
second. Many thanks to Bruce Tohack who 
was tlie first to notify us as to the error, and 
all the other readers who caught it as well. 
Now on to Layer 2. 

Going back to the overview of the 
OS1 model in the first article in the series, 
layer 2 is the Da la Link layer, and 
communicates with Layers 1 and 3. The 
most basic description of Layer 2's 
function would be that it receives data 
and routing information from Layer 3, 
and assembles them into frames which 
are passed onto the Layer 1, It also 
receives serial hi I si reams From the Layer 
1, and assembles these into frames, 
which are then passed onto Layer 3- Like 
most networking functions, the actual 
duties of this Layer are far more complex, 
and it is those duties, and the complexity 
therein that we wall look at in this article. 

Layer 2 

Base function 

The basic fund ion of the Data Link 
Layer is to provide services to the 


Network Layer. This centers around getting data from the 
transmitting machine to the receiving machine intact. There 
are three base methods for doing this: 

1) UnacknnwIe 1 1 get! Connectionless Service 

2) Acknowledged Connectionless Service 

3) Acknowledged Connection - Oriented Service 

The first method, unacknowledged connectionless 
service, is where the source sends independent frames to the 
source. This has some analogies to messages in a bottle. You 
write the message, pop ii in the bottle, and set the bottle in 
the water. It either gels there, or does not. You have no way 
to verify that it was successfully received, or that, in the case 
of multiple messages, that they were received in the proper 
order. This method may sound very unreliable, but in fact iL 
is used quite often. If the protocol you are using, such as TCP, 
has provisions for connection management, message 
reassembly, and acknowledgement at a higher layer, then 
there is no sense in having an additional level of 
acknowledgement and connection management in the Data 
Link Layer. As a result, most LANs use this type of service at 
the Data Link Layer level. The other reason for using this 
service would be in real time situations, where the time 
delays in setting up connections and retransmitting data 
would cause delays that would impede the function of the 
real Lime applications. 

The second type of service is acknowledged 
connectionless service. This is analogous to registered mail 
with a delivery receipt. You have no idea how the mail got Lo 
its destination, but you know that it was received or not. 
There are two ways to deal with acknowledgement errors. 
The first is to retransmil the entire set of data. While safer in 
theory, this is impractical for a number of reasons. The first is 
that if we are talking about a large amount of data, 
retransmitting the entire data set can take an unacceptably 
long time, especially over slow links. The other is that 
considering the chances of a lost packet here and there get 


John Welch <jwekih@atT.mm> is the Mac and PC Administrator for AER Inc. t a weather and atmospheric science company in 
Cambridge, Mass, l ie lias over fifteen years of experience at making computers work. Mis specialties are figuring out ways to 
make the Mac do what nobody thinks it can, and showing that the Mac is the superior administrative platform. 
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very high, especially over unreliable links, so in theory, you 
could run into a situation where you would never be able to 
stop retransmitting your data set. The second, and more 
common method is to only retransmit those frames that were 
lost. This method requires more sophisticated checking 
algorithms, but has a greater efficiency than retransmitting 
the entire message for every error. While lost frames are not 
a great issue with reliable media, such as fiber, when we la 
about wireless networking, the chances for lost frames ai 
much greater, and in fact, this is the type of service used ii 
the H02.1 lb wireless networking .standard. It is worth noting 
that providing acknowledgements at the Data Link Layer 
level is an optimization, not a requirement. Thai function can 
be, and often is handled at higher levels, 

The final type of service is acknowledged connection - 
oriented service. In this class of service, a connection is 
created before any data is transmitted, each frame sent over 
the connection is numbered, and each frame sent is 
guaranteed to be received. In addition, each frame sent is 
guaranteed to he received only once, and in the correct 
order. This type of service creates, what is essentially a 
networked bit stream. There are three phases to data 
transfers in this service. The first is the establishment of a 
connection. As part of this, frame counters are created on 
both sides, to keep track of which frames have and have not 
been sent. The second phase is the actual transmitting of 


data, and the tracking of the frames. The final phase is the 
connection teardown, and the disposal of Lite frame counters 
and other resources used. 

It worth mentioning here, that as far as the Data Link 
Layer is concerned, the Physical Layer doesn’t really exist. 
Alihough deal path of tile data has to travel through 

the logical path at the Layer 2 level would 
end connection between layer 2 on the 
■ 2 on the receiver. There arc a number 
eluding error correction T data delivery 
nportant thing to remember is that for 
really exist 

t, the Data Link Layer deals with 
both provides service to the 
the services provided by the 
^member, all the Physical Layer cares about 
... ^niiig bits from the Network Layer, and shoving them out 
onto the line to their destination. (Actually, all the Physical 
Layer cares about is shoving bits onto and receiving bits from 
the wire, ft has nothing to do with addressing, and in llie 
case of things like Ethernet, will actually look at all bits on 
the wire, relying on the higher layers to cheek things like 
destination addressing.) 



Think about it. 

Why should you 
have to buy a 
USB huh, then hang 
stuff off of it until it 
looks like something 
out of Edward 
Scissorhandsl 
Why tumble around 
under your desk 
every time you want to 
plug in another device? 
Instead, try this. 
A modular, stacking system 
of USB hubs, with adapters 
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And, oh yeah... 
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In any case, the structure used by the Data Link Layer is 
the frame, All data from the Network Layer is encapsulated 
into a frame, and sent on to the Physical Layer, Conversely, 
all bits from the Physical Layer is packed into frames, and 
sent on to the Network Layer. Although the specific sizes and 
contents of frames are determined by the hardware protocol 
used, such as Ethernet and Token King, all frames have 
certain structural commonalities. 

All frames have a Start Of Frame delimiter of some kind. 
This is some kind of structure that says “This is where the 
frame starts' 1 . They also all have some kind of End Of Frame 
delimiter, or Frame Check Sequence, that says “This is where 
the frame ends.” Since we are talking about the start and end 
of frame delimiters, tills is a good time to touch on exactly 
how frames are pulled out of bits on a w ire. There are about 
five ways to do this. The first, timing, is not used, and was 
never really used, as there is almost no way for any network 
to guarantee the timing between frames, or how long a frame 
takes to get from point a to point b. T his leaves us with four 
other methods of marking frames: 

1) Character Count 

2) Starting and ending characters, w ith character stuffing 

3) Starting and ending flags, with bit stuffing. 

4) Physical Layer coding violations 

Method one, character count, uses a header to specify 
the number of characters in a frame. When the Data Link 
Layer sees this header, it knows the end of the frame is 
exactly X number of characters follow the character count 
header, and there fore, where the frame ends. The problem 
with this is that there is no real way to deal with the 
character count gelling scrambled, if the transmitter sends a 
count of 23 characters, and the data gets scrambled, so that 
the receiver sees a count of 20 characters, then not only is 
that Frame garbled, but all following frames as well. Once 
this synchronization is lost, then even retransmission doesn't 
work, because there is no way to tell how many characters 
to ignore so as to skip the bad frame. Not surprisingly, the 
character count method is rarely used these days. 

The second method uses specific characters to specify 
the beginning and the end of the frame structure. The 
characters used are ASCII character pairs, with DLE STX used 
for the frame start, and DLF FTX used For the frame finish. 
(DLE stands for Data Link Escape, STX stands for Start of 
TeXt, and ETX stands for End of TeXtJ by using specific 
character sets as frame delimiters, and using those specific 
character pairs solely as frame delimiters, the character count 
synchronization issues are avoided. This works well for text 
data, but if we are dealing with binary or numerical data, 
then it is possible for those characters to occur in random 
places within the frame. The way to avoid this problem is to 
have the Data Link Layer insert, or ‘stuff, and extra DLE 
character in front of each occurrence of a delimiter pair in 
the wrong place. This way, the Data Link Layer on the 


receiving end knows that a double DLF pair is not a frame 
delimiter, and to remove one of the DLE characters from die 
frame data before passing the frame up to the Network Layer. 
Although this character stuffing works reasonably well, this 
entire method is too closely tied lo eight - bit ASCII data Lo 
he useful universally. 

The ibird method, uses bit pattern flags instead of 
character pairs as frame delimiters. This flag pattern is 
generally 01111110. To avoid synchronization errors caused 
by tli.it pattern occurring naturally, every time there is a 
series of five consecutive 1 bits, a 0 bit is inserted 
immediately after the fifth 1. This way, die flag pattern is 
never duplicated in the frame data, avoiding synchronization 
errors As well, this method is not tied to any particular 
encoding method, so it can be used more universally. 

The final method is used in I AN types where the data is 
encoded using bit pairs, be. a 01 pair is used to represent a 
binary 0, and a 10 is used Lo represent a binary 1. The 
transition from high to low, or vice-versa is what determines 
the data type. This makes it easy to take advantage of this to 
set frame boundaries. Since all data is a transition of some 
type, the pairs 00 and/or 11 can be used to set frame 
boundaries, as they will never occur anywhere else. 
Obviously, ibis method can only be used on networks with 
the proper type of bit encoding. In general, a combination of 
methods are used to delimit frames, so as to lessen the 
chance of error. 

In addition Lo the delimiters, all frames have source and 
destination address pairs. These are the hardware identifiers 
ihat name both the source and destination machines of the 
frame. The address pairs are placed at the beginning of the 
frame, so that they can be processed faster by a potential 
destination machine. 

The final common part of frame structure is the data 
field. This is the area that carries the actual data for the 
frame. The length of this is dependent on the hardware 
protocol used, such as Ethernet, Token Ring, FDD1, ATM, etc. 

Error Control 

Since we are sending frames back and forth, we need to 
make sure that what we send is what we receive, which leads 
us to another job of the Data Link Layer, error control. There 
are a number of areas in which the Data Link Layer provides 
this service. The first is in the area of frame delivery. When a 
frame is transmitted, it is good to know lhat the frame arrived 
at all, and if so, that it arrived intact. There are two ways that 
the Data Link Layer handles this. When a frame is sent, and 
received successfully, the receiver sends back a special control 
frame whose purpose is Lo acknowledge the successful 
reception of the frame. This is commonly called an ACK frame, 
or just ACK. If the frame was not received successfully, then a 
negative acknowledgement, or NACK frame is sent, (it is 
useful to point out here that the ACK/NACK do not indicate 
the data in the frame is intact, but rather that the frame itself 
was received correctly. The Data Link Layer does provide error 
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detection Tor the data in the frame, we will cover that later. It 
is also gtxxl to note that the error correction capabilities of the 
Data Link Uyer are optional in a protocol, and can be not 
used if this service is provided higher up.) This is useful when 
the frame is received, but what if the frame disappears 
completely? To handle this, timers are used. As each frame is 
sent, a timer is started. If the timer reaches its end before the 
ACK or NACK is received, then the frame is retransmitted. To 
avoid the receiver passing the same frame up to the Network 
Layer multiple limes, a sequence number is assigned to each 
frame, so that the receiver can distinguish retransmissions 
from original frames. 

In addition lu the basic frame structure, the Data Link 
Diyer can actually check to ensure that the physical bits in the 
frame at the receiving end are die exact same bits rhai were 
transmitted. There are two general ways to do ihis. The fust is 
to send enough information along with the packet so that the 
receiver can figure out what the garbled character must have 
been, This procedure uses error-correcting axles. The second 
is to allow' the receiver to deduce that an error occurred, but 
not what error or w'here, and request a retransmission of the 
frame. This method uses error-detection codes. 

in error correction, the data is analyzed, and any errors 
are able to be fixed. The methods we will cover here are 
based upon the work of Hamming. In comparing iwo binary 
words f such as 10001001 and 1011000T it is relatively easy 
to determine which bits differ, by Exclusive OKing, or 
XOR’ing the words, (When two digits are compared via XOK, 
the result shows if die digits were alike or not. So 1 XOK 1 
would give you a 0 as a result, since 1 and 1 are the same, 
whereas a 1 XOK 0 would give you a 1 as a result, since 1 
and 0 are different.) In the case of our words, there are 3 bits 
that differ, so they are said to have a Hamming distance of 3- 
To help detect and fix errors, check bits are used. These are 
bits within the word that, instead of containing data, are used 
to protect the integrity of die data. This means that iT you are 
sending eight — bit data words, that instead of their being 28 
possible combinations of data, there will be fewer, as the 
check bits will take up space within that eight - bit word. 

As an example, we take an eight bit word, and number 
each bit starting at the left with bit I. Each bit that is a power 
of 2, (1,2,4,8), becomes a check biL, and the remaining bits are 
used to hold the data. The check bit is used to force the parity 
of a collection of bits, including itself to be even or odd. A 
given check bit can be used in multiple calculations. For 
example, the bit at position 7 is checked by bits 1, 2, and 4, 
(1+2+4 = 7). So when the word arrives at the receiver, the 
parity of each check bit is examined* (usually, 0 indicates even 
and 1 indicates odd.) If the parity of each check bit is correct, 
then the parity counter is not incremented. If the parity is 
incorrect, then the counter is incremented by the position of 
that bit. So, if bits 1,2,and 4 are incorrect, then the counter 
would read 7, and that would be the bit that is inverted. This 
allows the receiver to set bit 7 to its proper value. In general, 
Hamming codes can only detect single errors. However, by 
arranging the words as an array, and sending the words out 
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column wise, instead of row-wise, the Hamming codes can 
then be used lo correct any error in that array. 

With error detection, the data is analyzed for correctness, 
but if an error is found, then Oil- frame is retransmitted, rather 
than Ixnng fixed. One of the most common ways of doing this 
is via a Cyclic Redundancy Code, or CRC In this case, ihe word 
is treated as a polynomial of k terms, with coefficients of 1 or 0 
only. As an example, 11100011 would be an eight-term 
polynomial with coefficients of 1,1,1,0,0,0,1,1, being the 
equivalent of x7+x6+x5+x1+xd Within CRC, polynomial 
division is used to create the CRC code. The first part is to agree 
on a generator polynomial, G(x) in advance. Both the high and 
low order bits of Gfx) must be I. To compute the checksum of 
a frame with m bits, corresponding to a polynomial M(xX the 
frame must be longer than G(x). The idea here is to append a 
checksum onto the end of the frame in such a way that the 
polynomial represented by the cheeksu mined frame is evenly 
divisible by Gfx), II there is a remainder after this division, the 
data is garbled somehow. The algorithm for this follows. 

1) Let r be the degree of Gfx). Append r 0 f s to the end 
of the frame so that it contains m + r bits, and corresponds 
to the polynomial XrMlx). 

Frame: 1101011011 

Gfx): 10011 

XrM(x): 1101 QUO110000 

2) Divide Gfx) into XrM(x) using Modulo 2 division 

3) If there is a remainder, subtract that from XrMfx) 
using Modulo 2 subtraction. The result is the checksummed 
frame to be transmitted, or Tfx), In our example, we would 
have a remainder of IM0. Subtracting 1110 from 
11010110110000 via Modulo 2 subtraction, (which is simply 
subtraction via XOR) gives us a T(x) of I 1010MOM 1110. 

The ability of the CRC method to defect errors is 
extremely high. As an example, if 16 - bit CRC is used, then 
all single or double bit errors are caught, all odd-numbered 
errors, all burst errors of length 16 or less, 99*997% of 17 - 
bit error bursts, and 99.998% of alll 8 bit or longer hursts. 

Regardless of which method is used, both error 
correction and error detection both work well to help insure 
reliable data delivery across networks. 

Media Access Control 

The final job of the Data Link Layer is to handle access 
to the media itself. In must LANs, there are four basic 
methods for handling media access control: 

1) Contention 

2) Token Passing 

3) Demand-priority 

4) Switched 
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The first method, contention is the most widely used for 
now. This is the method used by such l AN types as Ethernet, 
Fast Ethernet, and H02.11 wireless networks. While widely used, 
this is also a fairly primitive form of media access control. Each 
time any device on a contention network needs to transmit data, 
it checks the wire to see if any other station is transmitting. If 
not, then the device can transmit, otherwise, the device must 
wait for the media to clear up. This type of network also requires 
that all devices transmit and receive on the same frequency 
band. The media can only suppon a single signal at a time, and 
this signal takes up the entire band. In other words, this is a 
baseband transmission network. This creates iwo important 
implications, the first being that only one device can transmit at 
a time, and that a device can transmit or receive, but not both at 
once. This is called a half-duplex operation. 

In a contention based network, there are a numlx*r of tilings 
that are done to avoid collisions, which occur when two stations 
attempt to transmit at the same time. 'ITiese are based on frame size 
and timing. As an example, with the IEEE 802.3 Ethernet, frame 
sizes are specified to lx: IxMwcen 64 and 1324 octets in size. If a 
frame is going to lx* smaller than 64 fxtets, it is padded with Os so 
that it Is 64 octets in size, I he reason for this ties into Lhc timing 
part of collision avoidance, liming. If the minimum and maximum 
frame sizes are known, consistent quantities, then the amount of 
time it should take a frame to reach its destination can fx 
accurately calculated. Ihis time is ihe Lime it would lake for each 
frame to propagate across the entire network. In a contention- 
based, baseband transmission network, each frame must lie sent 
over the entire LAN to ensure than all recipients can receive it. In 
any cast", the frame can lx: destroyed by a collision anywhere on 
the network. As the physical size, and numlier of devices on the 
network grow, the probability of collisions increase. One of the 
ways that mcxlern networks avoid collisions is by using an inter- 
frame gap. Tills is a specified amount of dead air between frames, 
In a modem Ethernet network, the inter-frame gap is 96 bits long. 
So when a device transmits, not only must other devices wait for 
the frame to lx* transmitted, hut also for the inter-frame gap to lx 
transmitted, This gives the transmitting device time to either send 
another frame, or relinquish control of the media, without 
contending with all the other devices on the LAN. 

Another method is through the Binary Exponential Backoff 
Algorithm. This is used after a collision occurs. After a collision, 
time is divided into discrete slots, which are this size of the time 
ii takes a frame to travel round trip on die longest path allowed 
by the network type. In the case of 802.3 Ethernet, this is 
51,2jjsec, After the first collision, the stations that were affected 
wait either 0, or 1 of these time slots Ixforc trying again. If they 
collide again, they pick 0-3 time slots, wait, and try' again. If a 
collision occurs again, then 0-7 time slots are used. In each case, 
this Is a binary value, using 21 slots for die first collision, 22 for 
Lhc second, 23 for die diird and so on, hence the name of the 
algorithm. This occurs up to a maximum of 210 slots. Once that 
number of slots has been reached, then lhc stations wait a fixed 
amount of lime. If 16 consecutive collisions occur at this point, 
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the controller gives up, and reports a failure back to the 
computer Further recovery Ls then up to higher layers. 

Although collisions have a bad name, and rightfully so, 
they can be successfully managed through proper use of 
network design and devices, as wetl as using different types 
of network protocols in the areas where they are strongest. 

The next type of media access control is via a token passing 
mechanism, used most often in Token Ring and FDD1 networks. 
A token is a special frame that moves from device to device on 
the ring, (token - based networks use some sort of ring shape 
for their function ), and only circulates when the network is idle. 
The frame is only a few octets in length, and contains a special 
hit pattern. If a device needs to transmit data, it 'captures' the 
token, and converts that bit paLtern into a Start Of Frame, (SQF) 
delimiter, that informs downstream devices that Lius is now a 
data - bearing frame, and that they have to w ait until they get a 
token before they can transmit. The token is the sole way to 
access the network in this type of media access control. If a 
device receives the token, it has up to the default value in 
milliseconds for that network to convert the token into a data 
frame. If it does not have any data, a must release the token to 
the next device in the ring. If it does have data, then it converts 
the frame to a data frame, and begins transmitting. The recipient 
of tile data then modifies the frame to show an ACK or NACK. 
Once the data transmittal is complete, the originating station 
converts the frame back to a token, and sends it back onto the 
network. The advantages to a token - passing network are 
highest in situations where a predictable delay in data 
transmittance is needed. 

The obvious problem with a token-passing network is that 
of how to deal with the situation that arises w r hen a transmitting 
station goes down, or drops off the ring. Without a method of 
dealing with this, the entire network could stop functioning, as 
there would be no way to convert the data frame back to a 
token frame. To handle this, the idea of a monitor station was 
provided. 'Hie monitor station monitors the ring, anti ensures 
that the ring does not exceed a given time without the existence 
of a token. In the ease we described above, the monitor, (which 
is usually the first station on the ring, or if that station goes 
down, a monitor contention algorithm decides the new monitor 
station.) grabs the data frame, removes it from the ring, or drains 
it, and issues a new token. By using monitor stations, we avoid 
having an orphan frame endlessly circulating, and preventing 
any other station from transmitting. 

The third media access control method is that of Demand 
Priority Access Method, or PPAM DPAM is a round - robin 
arbitration method wherein a central repeater, or hub, polls each 
port connected to it. This is clone in port order, and identifies the 
ports with transmission requests. Once the ports that need to 
transmit are identified, then the priority of those [X>rts is 
established. Normally, and idle port transmits an idle signal 
indicating that it Ls not transmitting data. If a given pon is cleared 
to transmit data, the hub tells it to cease transmission of the idle 
signal. When the port hears its own 'silence’, it Ixgins to transmit 


data. Once data transmission begins, the hub alerts all ports 
connected to it that they may be receiving data. The hub then 
analyzes the destination address in the frame, compares it to its 
own internal link configuration table, and routes the frame to the 
port that connects to the specified device. 

In a DPAM network, the priority Ls controlled by the central, 
or root hub. The overall priority for the network is also called 
the priority domain, ThLs domain can include up to three levels 
of cascaded hubs. The central hub sends all traffic to the lower 
level hubs, wliich handle polling their own active ports once 
transmission has ceased. By using a priority mechanism, Lite 
problems of contention are avoided. No station can transmit 
twice in a row if other stations with equal, or higher priority 
requests are pending. If a station is transmitting, a sLation with a 
higher priority cannot interrupt that transmission. A higher 
priority request can however, preempt a lower level one. Finally, 
any lower level request that has waited for longer than 250ms is 
automatically raised to higher priority status. Although more 
reliable than contention networks, and cheaper than token - 
passing networks, DPAM was never a marketplace contender, 
and is virtually nonexistent in the modem LAN. 

The final media access control method, switching, isn’t as 
dearly defined as the other three, but is being used more and 
more in modem LANs to increase performance and efficiency. 
In essence, a switch decreases the network size for a given 
transmission to 3 devices: the switch, the transmitter, and the 
receiver. This increases performance by giving the data 
transmission the full bandwidth of the network for Lltai 
transmission by creating a virtual network just for that 
transmission. It increases efficiency by decreasing the number of 
collisions on a contention network, and by allowing Lhe use of 
the full bandwidth of the network, Switching lias also allowed 
the use of the VLAN, or virtual LAN, where traffic can be 
segregated by protocol, pon number, hardware address, etc. 
This also decreases the overall amount of traffic on the LAN. 
which decreases the error rate on the LAN. Switching can also 
be used by token-passing networks as well 

Conclusion 

Well we covered a lot for one layer, and really barely 
scratched the surface of Layer 2. There are whole books 
available that deal with this Layer alone, us it is one of the 
most complex layers in the 051 model, and one of the most 
critical. Hopefully, you now have a better idea of how this 
layer works, and why it is as important as it is. As usual, you 
are encouraged to read up cm your own. the sources i list in 
my bibliography are a good start. Next time, Liyer 3, the 
Network Layer! 
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Searchable Databases 
Online Stores 
Info Baskets 
Guestbooks 
Banner Ads 
Credit Card Transactions 

Counters 
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File Includes 
File Writes 
Web Based Email 
Classified Ads 
Discussion Groups 


Affiliate Tracking 
I/O Transactions 
A Time Calculations 
PGP Encryption 
Token Tracking 


It's time for you to take a look at MGI 

MG I, a plug-in to 4D's award-winning server, WebSTAR, is 
designed to provide functionality to otherwise static web sites, 
whether for a private intranet or enterprise - class ISP/ASP. 
MGI was specifically developed to be used by web graphic 
designers with no scripting or programming experience. If 
you know HTML, you know MGI. And if you are a 
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programmer, you can learn MGI by the time your pizza is 
delivered. You can try out MGI for free - right now - without 
obligation by downloading a fully - functioning demo at: 
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Introduction 

In previous QuickTime Toolkit 
articles, we’ve learned that a movie is 
composed of tracks and that each track is 
associated with one specific kind of 
media data. During movie playback, 
QuickTime uses a media handler (a 
component of type Media HandlerType) 
to interpret the media data and present it 
to the user in the appropriate manner. 
For example, if the media data for some 
particular track consists of compressed 
video data, the video media handler calls 
the decompressor specified in the image 
description and then draws the 
decompressed frames in the appropriate 
location. A media handler, however, does 
not typically concern itself with reading 
the media data from the movie file (or 
from wherever else the media data ts 
stored). Instead, the media handler gets 
that data from a data handler (a 
component of type l>ata HandlerType), 
which is responsible for reading and 
writing a media’s data. In other words, a 
data handler provides data input and 
output services for a media handler and 
for other parts of QuickTime, 

We identify a source of media data 
to a data handler by providing a data 
reference. As we’ll see shortly, 


QuickTime currently includes four standard data handlers, 
Kach data handler works with one specific sort of data 
reference. For instance, the URL data handler expects data 
references that arc handles to URLs, That is to say, a URL data 
reference is a handle to a block of data that contains a NULL- 
terminated string of characters. The other data handlers 
expect their references in other forms. 

A typical movie file contains data references to its media 
data in a data information atom, which is nested deep inside 
each track atom in the movie atom. In the previous article 
("The Atomic Calc" in MacTech, August 2000), we saw Lhat a 
shortcut movie file contains a data reference atom that 
identifies an entire movie file. Data references can in fact pick 
out any kind of data, not just media data. In general, if we 
want to tell QuickTime where to find some data or where to 
put some data, well use a data reference io do .so. 

In this article, we're going io see how to work with each 
of the four standard data handlers. At the very simplest level, 
this involves nothing more than creating an appropriate data 
reference and putting that reference into a file (as we did last 
time) or passing it to a Movie Toolbox function like 
NewMovieFmmDataRef, So well begin by learning how to 
create data references and call a few of the “FromDataKeP 
functions. Then well lake a look at some of the functions that 
we can use to work with data handlers directly. These are 
fairly low-level Functions that we won’t need to use very 
often. I fere, for fun, we ll see how to use them to write a 
genera I -purpose asynchronous file-transfer utility that relies 
solely on QuickTime Alls. Finally, loward the end of this 
article, we ll take a brief look at data reference extensions, 
which are blocks of additional data that we can associate will] 
a daLa reference to assist QuickTime in working with the data 
picked out by the data reference. As well see, data reference 
extensions can lie especially useful to graphics importers, u> 
help them avoid having to take the time to validate some 
block of image data, 


Tim Monroe's lizaais have started laying eggs. Will they hatch? Will the parents eat the young? Stay tuned for further details. 
In the meantime, you can contact him at monme#apple.com. 
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Our sample application this month is called QTDataRef; it 
illustrates how 10 work with data references and data handlers, 
Figure 1 shows the Test menu from QTDataRef, 


Test 


Open File Mouie... 

3€1 

Open Resource Mouie... 


Open URL... 

9S3 

Create Referenced File Copy... 

364 

Create RAM Copy and Play 

*5 

Transfer Remote File... 

*6 


Figure L 'Ihe lest menu of QTDataRef. 

Data Handler Overview 

When Quickl ime was first released, it included only one 
data handler, the file data handler, which can read and write 
data stored in files on a local file system, QuickTime version 
2.0 introduced the handle data handler, which allows the 
Movie Toolbox to work with data stored in memory rather 
than in a file, QuickTime version 2,5 added the resource data 
handler, which can read data stored in a file’s resource fork. 
More recently, QuickTime 3.0 added the URL data handler to 
support reading data from locations specified using uniform 
resource locators (URLs), 


All data handlers are components of type Data Hand lei Type, 
Data handlers are distinguished from one another by their 
component subtypes. The file Movies.h defines constants for 
three of the lour data handler subtypes: 

emim | 

Hand 1 eDataHandJ.trSubTypp = F0UR_CHAR_CQDE( * * hndl 1 ). 

ResoureeDataHand1erSUbType = F0UR_CHAR CODE(* rare" ) , 

URLDataHandUrSubType - FOUR CHAR CODEC utl * ) 

): 

And the hie Aliases.h defines the constant used for the file data 
handler: 

emitn t 

rAliasType * FDUR_CHAR_C0DE Coalin’) 

l; 

QuickTime also includes several other data handlers that 
it uses for its own private purposes and for which there is 
currently no public API. We won't consider these private data 
handlers in this article, but you should at least know that they 
exist (so that, for example, you aren't surprised if you iterate 
through all components of type DaiaHandlerType and find 
more than four of them), 

A data reference is a handle to a block of memory that 
uniquely identifies the location of some media data for a 
QuickTime movie or some other data that QuickTime can 
manage. QuickTime currently provides support for four types 
of data references, one for each of the available data 
handlers. To let the cat out of die bag: 


m nil 


Xjm: 


V u 

iLrf Y _ 




The JVIPEO-4 Multimedia Technology and Service Company 


Stiff Image and Streaming Media Technologies 


MPEG-4 Multimedia Streaming - the Internet's Next Step 

We invite you to join us at e-Vue, Inc. to create the MPEG-4 multimedia streaming 
products and services that are destined to revolutionize the Internet. MPEG-4 is a 
brand new ISO standard that, unlike all prior standards, was specifically developed to 
provide web-based multimedia content delivery and interactivity. e-Vue, Inc. Is a 
pre-IPO Samoff Corpora bon spin-off chartered to commercialize Samoffs extensive 
software and patent portfolio of MPEG-4 technology. e-Vue F s products and services 
provide the key enablers for high quality, reliable, and scalable delivery of video, audio, 
2D and 3D graphics, over the Internet, 

At e-Vue we are committed to career development for our employees and offer 
competitive salary, stock options and benefits packages. e-Vue provides employees 
with an extraordinary opportunity to grow In this fast-moving, high-tech industry. We 
are growing rapidly and looking for talented and motivated individuals to Join our team. 

• Software Developers and Architects: Windows, Mac, Unix 

a Expert Developers and Architects: Networking, Video, Audio, Graphics 

For full position details, please see our Website, http://www.e-vue.com. 

To respond directly, submit resumes to: 

• email: work@e-vue.com 

• fax: (732) 452-9726 

• mail: HR, e-Vue, Inc., 33 Wood Avenue South, 8th floor, Iselin, NJ 08830 



e-Vue, Inc. 

33 Wood Avenue South, 8th Floor 
Isetin, N.108830 
http://www.e-vue.com 






















* A file data reference is a handle to an alias record that 
specifies a file on a local storage volume (or on a remote 
storage volume mounted on the local machine). That is to 
say, a file data reference is an alias handle. Because the 
file data handler is of subtype rAliasTypc and uses alias 
handles as its data references, it is often called the alias 
data handler, fn addition, because it originalty handled 
files on the Macintosh hierarchical File system (IIPS), it is 
also sometimes called the HFS data handler. 

* A handle data reference is a handle to a -1-byte block of 
memory that holds a handle to some oilier block of data. That 
is to say, a handle da La reference is a handle to a handle. 

* A resource data reference is a handle to an alias record to 

which two pieces of information have been appended, a 
resource type and a resource 11). The target data is found 
in the resource fork of the Ole specified by that alias 
record, in the resource of the specified type and ID. 

* A URL data reference is a handle to a NULL-terminated 
string of characters thai comprise the URL The string of 
characters should conform to the relevant IETF 
specifications; in particular, some non-alpha numeric 
characters may need to he encoded using the hexadecimal 
equivalents of their ASCI! codes (for instance, the space 
character should be encoded as “%2U ,J ). 

In the following four sections, well investigate these four 
types of data references in more detail. Before we begin, 
however, let's introduce a bit of terminology that will be 
useful throughout this article. Let's call the block of memory 
to which a data reference is a handle the referring data. Anti 
let's call the data picked out by the data reference the target 
data (or just the target) of the data reference. So, for 
example, the referring data of a URL data reference is the 
string of characters, and the target data of a URL data 
reference is the data in the file picked out by that IJRL. 

The File Data Handler 

We can use the file data handler to open movies that are 
specified using a file data reference, which is an alias handle. 
Listing I shows how to create a file data reference for a given file. 

listing 1: Creating a file data reference 

QTDR MiikrFUeDuUKLf 

Handle QTnR_H«kciFUfiDstaRef (FSSpecPtr theFils) 

t 

Handle myDaLaRef D NULL; 

QTNewAlias{theFile, (AllaaHandle M&oyDstaRei. true); 

reiumCmyDataRef); 

I 


QTDRJVIakeFilcDataRef consists mainly of a cull lo the 
Movie Toolbox function QTNewAlias, which returns, in the 
location specified by the second parameter, an alias handle 
for the file specified by the first parameter. The third 
parameter is a Boolean value that indicates whether to create 
a minimal or a full alias record. (A minimal alias record 
contains only the minimum information needed to find a file; 
it’s generally much faster to find the LargeL of a minimal alias 
record, so that’s what well use here.) 

We could also have used the Alias Manager functions 
NewAlias (for a full alias record) or New Alias Minimal (for a 
minimal alias record) to create the file data reference. The 
principal advantage of using QTNewAlias is that it returns an 
alias handle even if the file specified by iheFile doesn't yet 
exist Both NewAIias and NewAliasMinimal return an error 
(fnfErr) — and do not create an alias record — if the 
specified file does not exist. As well see below, we 
sometimes want to create data references for files that we 
haven't yet created. (The Alias Manager does provide the 
NewAliasMrnimalFromFuilPath function that can create alias 
records for files that don't exist, but wed rather not have to 
deal with full pathnames just 10 do that.) 

Opening a Movie File 

Let’s consider a few examples of using file data 
references. First, we can pass a file data reference to die 
NewMovieFrom 1)alaRel function, to achieve exaedy the same 
effect as calling the OpenMovieFile and New Movie From Pile 
functions. Listing 2 defines the function 
QTI)RJ3etMovieFromFik\ which creates a file data reference 
and then retrieves the movie in the specified movie file. 

Listing 2: Opening a file specified by a file data reference 

OLD U^GrrMo vicFn >mFjk 

Movie QTOR_GetMovieFromFj1o (FSSpecFtr theFiie) 

1 

Movie myMovie * NULL; 

iUirKfle myUataRef - NULL; 

rayDataRef = QTDR. M.ikeFileDataRef (theFiie) ; 

If tmyDatalteJ NULL) ! 

NevMoviefc'romDiUaRefUmyHovie, neivMovieActive, NULL* 

my Da t aRe f, rAli a sType); 

DtsposeHandlehnyDatsKef): 

1 

return(niyMovie): 
l 

The last two parameters to the NcwMovieFromDataRef 
function specify* respectively, the data reference and the data 
reference type. Since we are passing it a file data reference, 
we set the data reference type to rAliasType. Note that we 
call Disposellandle to dispose of the data reference once we 
are finished using it. By the time NewMovieFromDataRef 
returns, the Movie Toolbox will have made a copy of the 
data reference, if necessary. 
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Creating a Reference Movie File 

Now let's turn to a more interesting example of using file 
data references. We learned in an earlier article (“Making 
Movies* in MacTech, June 2000) that a movie file might not 
contain the media data referenced by the movie's tracks; 
instead, that media data might be contained in some other 
file. A file that contains some media data is a media file, and 
the file that contains the movie atom is the movie file. (For 
simplicity, let's assume that our movies have only one track, 
a video track.) When the movie file and the media file are 
different files, the movie file is a reference movie file 
(because it refers to its media data and does not contain it). 
When the movie file and the media file are the same file, the 
movie file is a self-contained movie file. While generally we 
prefer to create self-contained movie files, if r s useful to know 
how to create a reference movie file. (Reference movie files 
can be useful, for instance, if we want to share some media 
data among several QuickTime movies.) 

One way to do this is to pass a file data reference to the 
NewTruckMedia function. Recall that NewTrackMedia is 
declared essentially like this: 

Media NewTrackMedia [ Track theTrack. 

QSTypc mcdiaTypfl. 

TineScale liKScale, 

Handle tiataftef, 

QSType dataRefType); 

The fourth and fifth parameters specify the data 
reference and the data reference type of the file (or other 
container) that is to hold the media data for the specified 
track. Previously, whenever we called NewTrackMedia, we 
passed NULL and 0 in those parameters, to indicate that the 
media file should be the same as the movie file. Now well 
create a reference movie file simply by specifying a media 
file that is different from the movie file. 

We're going to define a function 
QTI)RecreateRefereneeCopy that we can use to create a 
copy of an existing movie that contains the first video track 
in the original movie. The copy's movie atom will be 
contained in one file (theDstMovieFile) and its media data 
will be contained in some other file (theDstMcdiaFile), 
QTDli_CreateRderenceCopy has this prototype: 

OSErr fYrUJGCroatellpfCffftceGnpy (Movie theSrcMovie, 

fSSpecPir iticDatMovioFI le, FSEperPtr theDstMediaFile); 

The definition of QTDR_CreateReferenceCopy will look 
vaguely familiar, at least if you recall the sequence of movie¬ 
making functions that we encountered in the 
QTMM_CreateVideoMovie function (in the “Making Movies" 
article). It uses Create Mo 1 vie File, NewMovicTrack, 
NewTrackMedia, RegmMediaEdits, EndMediaEdits, and 
Add Movie Resource in the standard ways. There are only two 
important differences between QTD It _C rente Re fere nee Copy 
and QTMM_CreateVideoMovie. First, we're going to obtain 


the media daLa for the copy from the first video track in the 
existing movie; to do this, well call GetMovielndTrackType 
and GetTrackMedia to get the media from the source movie: 

mySrctrack = GetMovielndTrackType(iheSrcHovic. I, 

VideoMediaType. movieTrackMediaType): 
myKrcMedia " GetTrackMedia(mySrcTrack): 

Then we’ll call GetTrack Dime ns ions and 

GetMediaJlandlerl)escription to obtain some information about 
the source track and its media: 

GetTrackDimeajsitftts(jnySrcTraek, &myWidth ( tonyHeight): 
GetMediaHandlerDescription(mySrcMedis, fciuyType. Q r 0); 

When we create the copy movie, we’ll need this information 
to be able to specify the size of the new track and the type 
of the track's media. 

The second main difference between 
QTD R_CrcateRei erenceCopy a nd QTMM _Create VideoMov ie 
concerns the way we add media data to the new movie. 
Previously, we called an application-defined function to 
create the media samples and add them to the track's media 
(using AddMediaSample), Now, however, we've already got 
the media data for the new file — its just the media data 
contained in the firsL video track of the source movie file. So, 
instead, we can use the Movie Toolbox function 
InsertTrackSegment to copy the media data from the source 
track to the new track, like this: 

atyErr - InsertTrackSegment [mySi tTrack ♦ myDaftrack, 0, 

CetTracktJuration (mySrcTrack), 0); 

Here, InsertTrackSegment copies the entire source track (that 
Is, starling at time 0 and extending for the duration 
CictTrackDuration(mySrcTrack)) and inserts it into the 
destination track starting at lime 0. The result is that the new 
media file w ill contain a copy of the source track’s media data. 

There is one final detail we need to attend to. In order 
for the destination track to have the same visual 
characteristics as the source track, we also need to copy the 
source track matrix, clipping region, and graphics mode 
(among other things) into the destination track. Similarly, if 
the source track were a sound track, we'd need to copy its 
volume, sound balance, and other sound characteristics into 
the destination track. We could copy the visual settings by 
calling GefTrackMalrix and SelTrackMalrix, GecTrackClipKgn 
and SeiTrackClipRgn, and so forth, better yet, the Movie 
Toolbox provides the CopyTrackSettings function that copies 
all these settings in one fell swoop; 

CopyTraekSettingii (my£ rcTrack. Track): 

Listing 3 shows our complete definition of 
QTDR_CreaieReference€opy. 
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Listing 5: Creating a reference movie file 

QTDRJ: reate ReferrnceC :< jpy 

OSErr QTDR.CreatfiReferenceCopy (Movie theSrrMnvie, 

FSSpecPrr thfclktMovieFMe. FSSpecPir the&StffediaFile) 

! 

Track mySrcTrack = MULL: 

Media roySrcMedia - NULL: 

Movie royDstHovie * NULL: 

Track ray Dec Track - NULL: 

Media myDstMedia * NULL: 

Handle rayHediaRef - NULL: 

Fixed rnyWidth* myHeJght; 

OSType itayTypoi 

long myFlags “createKovieFileOeleteCwrFile | 

createMovieflleDontCreateResFile: 
short tiiylesRefNum - 0: 

short ntyResXD *■ raovielnDataForkKealD; 

OSErr myErr — paramErr: 

// get rhc first video mirk and media in the source mu vie 

nySrcTrack = CeiMovielndTrackType(theSrcMovie* 1, 

VideoMediaType, movieTrackMediaType): 
if (mySrcTrack — NULL) 
goto bail; 

mySrcMndla ~ Got TrackMed 1 a(mySrcTtark); 
if (mySrrMcdla — NULL) 
goto ball} 

//get some information .itxiui the sourer- trick and mctlia 

GetTrackLiiiienaionslraySrcTrack. &myWidth, ArayHeighi): 
GetM(*diaHflndlerDftncript ion(raySrcMcdia, &myType, Q, 0); 

// create a file iteo reference for the new media fife 

niyfiedittRef “ QTDR^MakeFileDataRef (theDstWediaFile); 
if (myMediaRef — NULL) 
goto bail; 

// create a file lor the destination movie data and create an empty movie 

rayKrr * FSpCrontctlUeDs tltediaFile, sigMoviePlayer, 

MovieFiieType, 0); 

if {myErr J= noErr) 
goto bail; 

// create a file lor the destination movie atom 

myErr » CreateMovicFIle(ihonsLMovieFile. sigHoviePlayer, 
israCur rent Script« nyFlags* 
foayftesKefNum, &myDstHovie); 
if (myErr 1» noErr) 
goto bail; 

// ;issjpn the default progress pmc to the destination movie 

Sf*tMovlpProgr«esProe(myDstMovie, (MovieProgre^sUFF) 1, 0); 

// Create ihe destination movie track and media 

myDstTrack - NevHovieTrack{rayDstMovie, rnyWidth, myHeight, 

kNoVcdume); 

myErr = GetMoviesErrorO ; 
if {myErr !•* noErr) 
goto ball; 

tnyDiitMedia - NewTraekMediaEinyDstTrack, myType, 

Gt?LHediaTireeScai^£j3iy3rcMedia), myMediaRef, rAliasType); 
myErr = GetMoviesErrorO; 
if (myErr 1- noErr) 
goto bail; 

//copy the entire wxirrr track into the tk-stination track; this copies the tracks mafia 
// samples into the destination media file 

myErr * BegiiiMediEiEdits{myDEtMedxa): 
if (myErr l* noErr) 
goto bail; 


rayKrr = TnsertTrackSegmenL(mySrcTrack, my Oat Track* 0* 

Ge tTra e kDu ra r ion (tny StcT rack), 0); 

if (myErr l- noErr) 
goto bail; 

CopyTrackSettings(mySrcTrack, mylL'irTrack}; 

rayKrr * EndKed taEil i ta (ray Dart Media); 
if (myErr l 13 noErr) 
goto bail; 

// add the movie atom to die dam fork of the movie rile 

myErr = AddMovieRessoiarcetiByDctMovie* rayficnRofNum, 

imyRcaTD, NULL): 

ba 11: 

return (myKrr): 


We call the Qll)R_MakeFileDataRef function to create a 
file data reference for the media file specified by the 
iheDstMediaFile parameter and we pass that dam reference 
to the NewTruckMedia function, as described earlier By 
default, QTDataKef names the new movie File “untitled.inuv" 
and the new media file “urttitled,tiat". When a user tries to 
open untitled.mov, the Movie Toolbox looks for untitled.dal 
to find the movie’s media data. If it cannot find that file, the 
Movie Toolbox displays the dialog box shown in Figure 2. 
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Tile, the mouie cannot play 
properly. 


Search | 


Figure 2. The missing data dialog box. 


Cancel [ 


One reason we prefer to create self-contained movie files Is to 
ensure that the media data Is always available, so ihe user won't 
ever have Lo see this dialup Ixue 

Before we move on t it’s worth mentioning that the Movie 
Toolbox provides the AddHmptyTrackToMovie function, which 
we could use in listing 3 instead of NcwMovieTrack, 
NewTrackMedia, anti Copy!rackSettings, like this: 

myErr - AddEmptyTrackToMoviefraySrcTraek, myBstMovie. 

jnyMediaRef, rAlIssType. iniyDstTrack); 

it (myErr t» noErr) 
goto bail; 

myDstHedia - GetTraekHediaCrayDstTrack); 

AddkmptyTrackToMovie makes a copy of an existing track, 
either in the same movie or in a different movie; it doesn't 
actually copy the media data, hut it does copy the track settings. 
The source code files accompanying this article provide an 
alternate version of the QTORjCreateReferenceCopy function 
that uses AddKmpryTrackToMtsvie. 

Tin: Handle Data Handler 

The handle data handler is used to read data from and write 
data to a location in memory. That location is specified using a 
Macintosh handle, A handle data reference is a handle to that 
handle. Listing 4 shows how to create a handle data reference. 

Listing 4: Creating a handle data reference 

0 IUK_M;iki’UimdliJ)al;tKer 

Handle QTDR MakeHandleDataRef [Handle theHandle) 
t 

Handle my Daly Ref “ NULL: 

myDataRef * NevIJandleClear (aizeor (Handle)); 
if (myDataRet !- MULL) 

BlockMoveUtheHandle* 'tayDataRet, sizeof(Handle)}: 
return (snyBataRe f); 

) 


Here we allocate a relocatable block of memory that is 
the size of a handle (4 bytes) and then copy the handle 
passed to the function into that block of memory. The result 
\$ just what we want, a handle to the original handle. For an 
even simpler routine, we can replace the middle three lines 
of code by this one line: 

PtrTaHandUtheHandle, &myDataRef, siseof(Handle)); 


The Memory Manager function PlrToIland allocates a 
new relocatable block of memory of the specified size and 
then copies the data specified by ils first parameter into thal 
block. In a little while, we'll encounter PtrAndlland, a cousin 
of PlrToIland that appends the data in a pointer to an 
existing handle. 

The handle data handler is useful for many tasks. It’s 
useful for playing movies that can fit entirely into RAM, and 
it’s useful for handling images when the image data resides 
in memory and not in a file. In the latter case, we can just 
create a handle data reference from the handle that holds the 
image data and pass it to GetGraphicsImporterForDaiaRef to 
gel a graphics importer than can manage the image data, 
Similarly, to play a movie stored in RAM, we can create a 
handle data reference and pass it to NewMovieFromDataRet 
In this case, the block of memory referenced by the handle 
must contain the movie data and the movie atom. 

To create a movie whose data is stored in RAM, we 
could use NewTrackMedia as illustrated in the previous 
section, passing it a handle data reference instead of a file 
data reference. Or, even more simply, we can exploit Ihe 
ability of the Flatten Movie Dai a function in flatten a movie 
into a location specified by a data reference instead of by a 
file specification record. The third parameter to 
FlattenMovieData is declared as a pointer to an FSSpec 
record, but we can set the flag 
f lattcnFS S pecP t rl sD at a Ref Record P t r to instruct it to interpret 
that parameter as a pointer to a data reference record, 
defined by the Data Reference Record data type: 

struct BataReferenceRecord t 

OSType dataRefType: 

Handle datsKef: 

I: 


So all we need to do is create a handle data reference, fill in 
a data reference record with the appropriate information, and 
then pass the address of thal record lo FlaitenMovieData in 
place of the FSSpecPir. Listing 3 shows an excerpt from our 
QTApp \ landieMenu function that handles the “Create RAM 
Copy and Play” menu item. 


Listing 5: Creating a movie in RAM 


ease IDH CREATE RAM C0PY_ ANIL PLAY: 


if (myMovie != NULL) 
Movie 
Handle! 

Handle 

DataReferenceReeord 


EtyNpwMovie = NULL 
myltatafief ■ NULL; 
myHandle - NULL; 
myDataRetRecord; 


QTA pp_HaiKlk:Mnnii 


inyHandle - NewHandleCIear (0); 
if (myHandle = NULL) 
goto bail; 


my Da taRef = QTUft_Ha k cH a nd 1 efta I n Re f ( mytfa ndle); 
if {myDataKef = NULL) 
goto bail; 


jnyDataRefRecord.dataRefType - HandleDataHandlerSubTypc; 
tnyDataRefRecord.dataRef ** myDataRef: 
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rayNewMovie = FlattenMovieDsta( myMovie, 

flattfluFSSpfiCPtrT^nataRefRetardPlr, 
(FSSpccPirjfemyOataRefRecord* 
s ^MoviePlayer r 
smSystemScript, 

OL): 

if [myNewMovie !-■ NULL) f 

QTDR.PlayM ovieF r omRAM f nryNewMov i e); 
DisposeMovie(myNewHoYie); 

I 

bail: 

If (myUandle (* NULL) 

Di spcs eHand 1 e {my Handle): 

if (rayDataRef t- NULL) 

DisposeHandle[myDataRef); 

! 


In tills case, once we've created Llie movie in RAM, we call 
the function QTDRPla yMov i eFromRAM to play the movie in a 
window on the screen. Then we dispose of the new movie and 
the handle that contains the movie data, along with the handle 
data reference* 


The Resource Data Handi er 

The resource data handler was introduced in QuickTime 
version 2,3 to allow data to lie read from a resource in a file's 
resource fork. Listing 6 shows how to create a resource 
data reference. 


lasting 6: Creating a resource data reference 

QTDR MaktRt^UK^IMaKtf 

Handle QTDR_MakeResoitrceDataRef [FSSpecPtr theFile, 

OSType theResType, Sint 16 theResTD) 

I 

Handle myDataRef = NULL? 

OSType myRe-Type: 

Slutl6 myKeslD; 

OSKrr oiyErr « noErr: 

myDataRef - QTDR H&keFileDgtaRefftheFil e); 
if (myDataRef = NULL) 
goto bail; 

// append the resource type and H> to the data reference 
rcyiiesType = EndianUA2_NtoBftheResType): 
myResID - EndianS16_NtoB(theResID); 

my Err = PtrAndHandUmyResType, myDataRef, 

s tzeof(myResType)}; 

If (wyErr ™ noErr) 

myErr ^ PtrAndlland(kmyKeslD, myDataRef. sizeof(myResID)): 

bail: 

if [myErr !— noErr) 1 
if (myDataRef != NULL) 

DisponeRandle(myDataRef); 
myDataRef - NULL;' 


return(myDataRef): 

I 

In QTDR_Ma keResourceDatakef, we begin by creating a 
file data reference to the specified file. Then we call 
PlrAndHand to append the resource type to the referring 
data of that data reference, and then we call PirAndlland 
once again to append the resource ID. Note that the resource 


type and !l) must he converted to big-endian format before 
being appended to the referring data. 

We won't spend too much time considering the resource 
data handler, largely because we prefer not to keep our 
rnovie or image data in resource files (so LhaL it’s easily 
transportable to non-Macintosh operating systems). To show 
you that it works on Macintosh resource files, I've added the 
menu item “Open Resource Movie../ Lo the QTDataRef 
sample application; I've also included the file RcsBased.mov, 
which contains a movie stored in a resource. 

There is another reason why the resource data handler 
is of limited interest to us: it can read data from resource 
files but cannot write data to them* To see this, let's suppose 
that myDataRef is a resource data reference. Then we can 
call the GetDataHandler function like this: 

myComponent = GetDataHandler (myDataRef. 

Resou rceDataHand 1 e rSubType, kDataHCanW r i te.) 

GetDatal Iandler returns the best data handler for the 
specified data reference and data handler type that provides 
the services specified by the third parameter. In this case, 
weTe asking for a resource data handler that can write data. 
After this line of code completes, however, the value 
returned in myComponent will be NULL, indicating that 
there Is no such resource data handler. 

The last reason weYe going to ignore the resource data 
handler in the future is perhaps the most obvious: if we do 
want to access some movie or image data stored in a 
resource, we can simply load that data into memory (by 
calling Gel Resource) liiuI then use the handle data handler* 
So the resource data handler is largely redundant* 

The URL Data Handler 

We can use QuickTime to open movies and images that 
are specified using URLs. A URL is the address of some 
resource on the Internet or on a local disk* Typically, a URL 
is a string of characters like u http://www.appie.com". The 
initial portion of die URL, which precedes the first colon (:), 
is the URL’s scheme or protocol. In tills case, the scheme is 
“littpY for the hypertext transfer protocol QuickTime 
provides data handlers that can work with URLs whose 
scheme is "http", “ftp” (file transfer protocol), "rtsp" (real-time 
streaming protocol), or "file" (picking out a file on the local 
Hie system). Note that there really isn’t just one URL data 
handler; there are in fact several data handlers that support 
URLs. For instance, the file data handier will ultimately be 
useel to ha nd Ie 11RLs w ht >se scheme is “file*. Still, we access 
these data handlers using URL data references* 

As we've already seen, a data reference for the URL data 
handler is a handle to the NULL-terminated string of 
characters that comprise a URL. So it's relatively easy to 
create a URL data reference: just allocate a relocatable block 
of the appropriate sue and copy the URL into that block. 
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Listing 7 defines the function QTDIi.MakelJKLDataRef, which 
creates a URL data reference for a given URL. 

Listing 7: Creating a URL data reference 

QTDR_Hbkcl FULDiitaRcf 

Handle QTHR^HaJteURLDataHef (char ‘theURL) 

1 

Handle myDataRef = NULL: 

Size tnySize = D; 

// grt the size of the URL plus she terminating null byte 

mySize = (Size)strleu(theURL) + 1 ; 
if (mySize = I) 
goto bail; 

If allocate a new handle and copy the URL Into die handle 

myDataRef = NcwTtandleClcar(wyStze); 
if (nyUntakef != NULL) 

hloekMove (theUKL, ‘myDataRef . tuySize) ; 

bail; 

return{myDataRef): 

I 

If a URL picks out a movie file, we can call 
QTDR_Makd IRLDataRef to create a URL data reference for ii and 
then pass that data reference to the NewMovieFroniDataRef 
function to open the specified movie file. Listing 8 defines the 
function QTURL_NewMovieFromLJRL that takes a URL and 
returns a movie identifier for the movie addressed by dial URL. 
O'11) R GetMovierrc>n 1 1; RL is j u si 1 ike Qll >R_GetMewieFncjmFile, 
except that it uses URL data references. 

Listing 8; Opening a movie specified by a URL 

QTDR GetMovicFromURL 

Movie QTDR_GetMnvieFromirRL (char ‘tbeURL) 


Movie myMovie = NULL: 

Handle myDataRef = NULL; 

ntyDataRef = QTDR MakeURLDataRef (thfiURL): 
if (myDataRef 1“ NULL) [ 

NewMovloFromUataRef fimyMovle, newMovieAct Ive, NULL. 

icy DataKef , IfRLDatalland 1 erSub Type); 

Dispos e Hand1e(myDataR e f) : 

} 

return(myMovie): 


The QTDR_GetMovieFromURL function is a targe part of 
what we need Lo handle the ‘'Open URL...’ 1 menu item 
(supported both by QuickTime Player and by our sample 
application QTDataRef). But it isn’t quite all of what we 
need. First, of course, when the user selects “Open URL... M , 
we need to obtain a URL from him or her. QuickTime Player 
displays the dialog box shown in Figure 3, which contains 
space to type in a URL, as well as a pop-up menu containing 
a list of recently opened URLs. 


Enter an Internet UHL to open: 

jftp://ftp,apple,com/ineD/media/im9t-feature&.fnoo | |_tj 

f Cancel j t. E . Jl i 


Figure & the Open URL dialog hox of QuickTime Flayer. 

For the moment, well he exmtent to display the dialog box shown 
in Figure 4, which does not provide 1 the jxjp-up menu. (Providing 
a pop-up menu or some other kincl of list for recently’ accessed 
URLs is a grxxi idea, however, since URLs are often longer than 
25n characters, which is the most our current code will support.) 



Figure 4. The Open URL dialog bar of QTDataRef, 
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The code to display and manage this dialog box is 
contained in live function QTDR_GeilIRLFmmlLser, which we 
won’t consider in detail here; it's really quite similar to the 
function QTInfo_EditAnnotation, which we considered in a 
previous article (see “The Informant” in MacTech, July 2000). 
iLs also useful to get the basenaine of the URL so that our 
movie window has a title (the basename is the portion of the 
URL following the rightmost URL separator)* See the file 
QTDataRef.c for the function QTDR_GcLURL Base name, 
which we use to find that basename. 


File Transfer 

We’ve learned that QuickTime supplies a data handler 
that can read data from remote locations specified by a URL 
and a daLa handler LhaL can write data into files on the local 
file system. We can use both of these data handlers at the 
same time to read data stored remotely on the Internet and 
write it into a local file* This gives us, in effect, a network 
file-transfer capability that operates using only QuickTime 
APIs. Moreover, Quicklime supports calling these data 
handlers asynchronously, so that our application can perform 
other processing while the file transfer is taking place. In this 
section well see how to do all this. 

Our ulterior motive here is to get a glimpse of the lower- 
level functions supported by data handlers. Hitherto, we've 
pretty much always used data handlers indirectly, by passing 
data references to Movie Toolbox nr I CM functions* or simply 
by embedding data references in files. Now we want to see 
how to work with data handlers directly. 

In overview, our file transfer wall proceed like this: get 
an instance of the URL data handler and configure it to copy 
data from a remote file into a memory buffer. Then get an 
instance of the file data handler and configure it to copy data 
from that buffer into a local file. Then keep copying data into 
and out of the buffer until the entire remote file has been 
cci p i ed. To ma ke it eas y U >r this 1 1 > w ork a s y nch rc>nou si y, our 
file-transfer code is going to rely on a few global variables, 
declared like this: 


Ft r 

Componentlnetanc e 
Campon entInsta nc e 
Da taHC omp1e tion UPP 
DataHCnmp] etiontJFF 
10E1£ 

long 

Boolean 


gDataBuffer =■ NULL; 
gDataReader = NULL; 
gDataWriter = NULL: 
gReadDataHCompletionUPP = NULL; 
j>Wr i teDatafiCompIetionUPF ~ NULL: 
gHytesToTransfer = QL; 
guyLesTransferred = QL; 
gDoneTransferring = false; 


The variables gDa La Reader and gDa La Writer are the 
component instances of the URL data handler that reads data 
and the file data handler that writes data. gDataReader puts 
data into the buffer gDataBuffer, whence gDataWriter gets 
the data that it writes into the local file. The asynchronous 
nature of the file transfer is achieved largely by two 
completion functions, to which gReadDataHCompietionUPP 
and gWriteDaiaHCompleLionUPP are universal procedure 
pointers. Finally, the global variables gBytesToTransfer, 


gBytesTransferred, and gDoneTransferring keep track of 
information while the transfer is underway. 

Creating the Local File 

The first thing we need to do, of course, is create the 
local file into which the remote file data is to be copied. Let’s 
suppose that theFile is a file system specification for the local 
file (which we perhaps got from the user by calling our 
fra me wc >rk f u nc L i on QT F ra me_P u LF i I c). Wc should first d e let e 
that file* if it already exists, by calling FSpDelete; 

FSpDelete(theFile); 

If the specified file doesn’t exist, FSpDelete will return the error 
ccxle fnfErr, which we can safely ignore. Then we can call 
ESpCreaLe to create a new empty file, like this: 

myEtt * FSpCreaieCtheFile* kTranti-FileCreator, kTtansFtleType* 
smSystemScript); 

(Note that we are hard-coding the file’s type and creator codes 
here; 111 leave it as an exercise for you to concoct a more 
intelligent way to set these values*) 

Opening and Configuring Data Handlers 

Before we can work with a data handler, we need to open 
an instance of ihe appropriate data handler component. We saw 
earlier that we can find a particular data handler by calling 
GetDatallandler, passing it a data reference, a type, and a set of 
Hags lhai indicate the data-handling services we need it to 
provide* If theURL is a C string that specifics the remote file and 
theFile is a pointer to a fife system specification for the local file 
into which the remote file data is to lie copied, we can create the 
required data references like this: 

Handle niyKeaderKef - QrUK_MakeURLl)at£iKef (theURL); 

Handle myWriterRef = QTQRJtekeFileDataKef(thrfile); 

And wc can open the appropriate data handlers with tills code; 

gDatattender " OpenCompnnpnt(GetDataHandTer(myReaderRef, 

URUlat ullamll erSubType. kDataHCknRead)); 
gDataWriter - OpenComptJiient(GetDataJlandler{i^Writerllef * 
rAliasType. kDataliCanWrite)) ; 

As you can see, we re asking for a URL data handler that 
can read data and a file data handler that can write data. 
Once we’ve got our data handler instances, we need to 
configure them by telling them which data references they 
are going to work with. We also need to have them open a 
connection to the targets of those data references. We can set 
the data references by calling DataHSetDataRef, like this: 

my Err = DataHSetDataRef(gDataReader, myReaderRef); 
myF*rr = DataHSetDataRaf(gDatsWriter, myWriterRef); 

Then we can open the appropriate connections by calling 
DataHOpenForRead and Data HOpenFor Write: 

myErr * DataHOpenForRead(gDataReader); 
tnyErr - DataHOpanForWrite (gDataWriter): 
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Transferring Data Synchronously 

It might seem like we haven't done much work yet, but 
(believe it or not) we are ready to begin transferring data 
from Lite remote file into the local file. At this point, we have 
a choice: we can transfer the data synchronously (that is, 
waiting for all the data to arrive before continuing with any 
other work) or asynchronously. Ultimately we want to have 
our transfers proceed asynchronously, hut let's take a 
moment to see how to do them synchronously. 

To perform a synchronous transfer, we can call 
DataHGetData anti DataHPutData. These functions require 
the intermediate buffer to be accessed by a handle (not by a 
pointer, as with asynchronous transfers). We can call 
DataHGetFileSize to see how many bytes we need to transfer 
and then allocate a handle of that size: 

myErr - DataHGetFiipSizetgLlaLaReader, SigBytesTaTransfer); 

Handle gDataBuffer = NewHandieCiear(gEytefiToTransfer); 

If gDataBuffer is successfully created, we can then transfer 
the remote file to the local file with Lhese four tines of code: 

DataHGeiDaiatgDataReader, gDataBuffer, OL, OL, 

gBytesToTransfer): 

DatallCloseForRead (gEataReader) ; 

DacaHFutDatafgDaraWriter, gDataBuffer, OL. NULL, 

gBytesToTransfer): 

DataHCloBeForVritetgDataWriter); 

All we need to do is fetch the remote data into the 
intermediate buffer, close the connection to the remote file, 
write the data into the local file, and then dose the 
connection to the local file. This code assumes, of course, 
that we can allocate a buffer large enough to hold the entire 
remote file. With very little work, you could generalize this 
code to work with files too large to fit entirely into the 
available HAM. (Well do this below, when transferring 
asynchronously,) 

So there you have it: with barely a dozen lines of code, 
weVe managed to copy a file located somewhere out on the 
Internet into a local file. The downside here is that the 
transfer occurs synchronously and is limited to files that can 
fit entirely into RAM, Let's remove these two limitations. 

Transferring Data Asynchronously 

We can remove the limitation on file size rather simply, by 
allocating an intermediate buffer of a set size and then reading 
and writing chunks of data of that size. We'll allocate a buffer 
t hat is 10 kilobytes, like ill is: 

^define kDataBufferSi-ze LD24*10 

gDataBuffer ” NewFtrClearCkBataBufferSiza); 

So all we need to do is read a chunk of data of size 
kDataBufferSize, write that chunk of data, read another 
chunk of data, write that chunk, and so on until the entire 
remote file is transferred. Of course, eventually well 
probably end up with a chunk tltat’s smaller than kDataBulfeiStze, 


so we ll need to keep track of how much of the file remains to be 
transferred and adjust our reads accordingly. 

We can achieve an asynchronous transfer by using the 
functions DatallReadAsync and Da tali Write to read and write 
data. These functions queue up a read or write request to the 
data handler and then return immediately, without waiting 
for the request to he serviced. The request will he serviced 
at some later time, when we call DataHTask to task the daLa 
handler. Once ihe request is serviced, ihe data handler 
executes a data handler completion function that we specify 
when we call DataHReadAsync or DataHWrite, 

A data handler completion function takes three 
parameters: a pointer to the buffer into which data was 
written or from which data was read, an application-specific 
reference constant, and an error code. Well ignore the error 
code and use die reference constant to hold the number of 
bytes Just written or read by the data handler. 

We hegin the file transfer by reading some data from the 
remote file. We could simply call DataHReadAsync directly, 
passing it the appropriate parameters. Instead, however, 
well he a bit clever here and call our write completion 
function QTDR JWriteData Completion Proc, passing it 
parameters that indicate that we ve just successfully finished 
writing 0 bytes: 

QT0R_WriteDataCotnp 1 etionProc(gDattiBuffer, OL. noErr): 

The reason for this is simple our 
QTDR_WriteDataCompletionProc function (defined in Listing 9) 
contains code for figuring out how many bytes to request and 
then for issuing that request. 

Listing 9 = Res ponding to a wr ite operation 

QTDRJVri icUaUComplctiouPn m: 
PASCALJtTN void QTDOriteDataCnmp 1 oi lortProc 

(Ftr theRequest, long itieRefCon, OSErr theEi r) 

#pragma unusedCtheErr) 
long myNumBytesToRead: 
wide myWide; 

// Increment our tally of the number of bytes written so f;ir 

gBytesTransferred +- theRefCon: 

if (gBytesTransferred < gByLeaToTransfer) I 

// iticnc is still data to read and write, so schedule a read operation 

// determine how big a chunk lu read 

if (gBytesToTransfer - gBytesTramsfotred > 

kllataBuffe rSize) 

myNurnBytesToRead ■= kDataBuffetSize; 

else 

myNumBytesToRead “ gBytesToTransfer - 

gByte^Transfor red: 

myWide.lo - gliytesTransf erred : // read from the current offset 

inyWIde.tii s 0 : 

// schedule a read operation 

DataHReadAsync(gDataReader. 

theRequest, // the data buffer 

my NumH y L e sToR e ad, 

kroyWide, 

glte adEa t aHComp 1 et i onlJ P P, 
atyNumBytesToRead): 
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I else I 

// wc'vc I r;inskmd .ill thr ihu; sti :i Dig to tell ils lo dose down the diu.i lumikrs 

gDoneTransferring ” true: 

I 

I 

As you can see, we first update the global variable 
gBytesTransferred that keeps track of the number of bytes 
already transferred, Then we figure out how many bytes 
remain to be read from the remote file; we read that number 
of bytes, if il\s less than the size of our intermediate buffer, 
or else we read an entire buffer of data. Finally, we cull 
DataHReadAsyne to schedule a read operation* Notice that 
we specify Lite gReadDutallCompletionUPP as the read 
completion function. 

Once some data is read into the local buffer, our read 
completion function will be executed. Listing 10 shows our 
read completion function. IPs even simpler than the write 
completion function; all it does is schedule a w rite operation 
to copy the data from the buffer into the local file. 

Listing 10: Responding to a read operation 

QTDR^ RraiiDji u( rim pie I i c >n Prcuc 

PASCAL_RTN void GTDRJteadDataCorapletianProc 

(Ptr theRequest. long theRefCon, OSErr the'Err) 

I 

#pragnjo unused(theKrr) 

// wt- just finished trading some data, so schedule a write opewtitm 
DatadWrite (gDutiiWrlter, 

theReques t, // the data buffer 

gBytesTransfer red. // write from the trurrenr offset 

th eRe f Con * // Uil iiu mber of bytes to write 

gWriteDataHCompletionUPP, 
thcRefCon); 

] 

In this case, theRefCon contains the number of bytes just 
read from the remote file, which is the number of bytes that 
should be written to the local file. Notice that now we specify 
gWriteDataHCompIetionUPP as the write completion function. 
The read and write completion functions keep scheduling write 
and read requests, specifying each other as the completion 
function for those requests. So we keep successively reading 
and writing data, until the entire file is transferred. 

Tasking the Data Handlers 

There is one final step needed to make this all work. 
Namely, we need to give the data handlers some processor 
time to do their work. We do this by periodically calling 
DataHTask, On the Macintosh, we can insert calls lo 
DatallTask into the application function 

QTApp_HandteEvenl f which is called by our application 
framework every trip through the main event loop. Listing 11 
shows the definition of QTAppJTandleEveni in QTDataRef. 


Listing 11: Tasking the data handlers 

QTAppJiandle Event 

Boolean QTApp HandleEvent (EventRecord *theEvent) 
f 

^pragma unusedUheEveni) 

// if wCne done, dose down the data handlers 

if CgDoneTransferring) 

QTDR ClofieDewriHandiersf): 


// give Ihc (Una handlers some time. If they are still ac tive 

if [ghat a Reader !“ HULL) 

DataHTask(gBataReader ): 

if (gharaWriter t— NULL) 

DataHTask(gDataWriter): 

return(False): 


If the file is done being transferred, then QTAppJl landleEvent 
calls the function QTDR_CloseDownNandleis (defined later) to 
dose things down. Otherwise, it calls DataHTask on Ixsth the URL 
data handler and the file data liandler. At most one of them will 
have some work to do t but it doesn't hurt to task both of them. 

Our Windows framework does not however call 
QTAppJ-kmdleisvent periodically, so we ll have to do that ourselves. 
Probably Lhe easiest way Is to install a timer task, like tlusr 

gTIuerlD ■=- SeLTImer (NULL, 0 t kQTDR TimeOut, 

[TIMERPROG)QTDR TimerProc); 

The timer callback function QT1 >RJIimerProc, defined in Listing 
12, simply calls QJApp HandleEvenL 

Listing 12: Handling timer callbacks 

QTDS^TimerProc 

void CALLBACK QThR_TiraerProc: (HWND theWnd. DINT theMessage. 

PINT PTR the ID. DWORD theTinte) 

I 

^pragma unused(theWnd, LheMussagc. iheTD. theTlme) 

QTAp p Jtsnd leEveat (HULL): 

] 
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Installs in minutes! 



Dr. Bott Moni Switch adb or usb 


Do you need 4 monitors and 4 keyboards for your 4 servers? 
With Dr. Bott Mori Switch you car connect a single keyboard 
and monitor to up to 4 machines at once! A simple flick of a 
switch directs the video input and keyboard commands to the 
appropriate CPU! Available in USB and ADB models, with 2 
or 4 machine support, and bundles with USB PCI cards so 
you can mix and match USB and ADF1 machines with the 
same Mont-Switrh! Great for programmers to do back 
ground compiles, ideal for server rooms overcrowded with 
monitors and keyboards! 


As low as 



$ 129 ® 


Macsense USB Full Size Keyboard Macsense Internet Sharing Router 


Just plug this keyboard into your Mac and start typing! The 
UKB-600 keyboard from Macsense is designed to g?t you 
typing quickly and easily without any hassle or compatibility 
worries It features two tone translucent design, colored to 
match your favorite flavor ol Macintosh. It olfers soft touch 
with positive tactile feedback and build built in USB port on 
either side of the keyboard. Includes a 5‘ USB cable and is 
100% Macintosh compatible, simply plug and play, as easy 
as Macintosh! 


i 


Soil 


$44 


as 


Looking to get your whole office online without shelling out 
thousands of dollars? If so, the XRoutcr Internet Sharing 
Hub offers the perfect solution. This amazing Ethernet-to 
Ethernet hub connects an entire network of up to 252 users 
to the Internet using only one ISP account and one Cable or 
DSL modem! 




































We remove the timer task once the data toaster is completed 
(see Listing 13 below), 

It's important to know thaL a data handler may execute 
our requests to read and write data asynchronously or not, 
even if we specify completion functions. If the handler deckles 
to operate synchronously, then ii will noL return immediately 
when we cull DataHReadAsync or DatalTWrite; instead, it wall 
perform the requested operation and then return. We still need 
to call DataHTask, however, to give the data handlers an 
opportunity to execute their completion functions. 


Finishing Up 

When the write completion function 
QTDR_WriteDataCompletionProc determines that all the data 
has been read from the remote file and written into the local 
file, il sets the global variable gDoneTraasferring to true. When 
QTApp_Handie£vent is called and gDoneTransfening is true, 
QTApp_l landleEvent calls QTDR_CloseL>ownHandlers r 
defined in Listing 13* 


Listing 13: Closing down the data handlers 

QnHLOoscDowisKandkTs 

void QTDR CloseDovoHandlers {void} 

1 

if {gDytaRcadcr !- NULL) ( 

DaL a] iCloaeFo rRead(gData Readn r); 

CloEeConipoiieiiL CgDaiaHeader]: 
gDataReader « NULL: 

I 

If (gDataUriter 1 = NULL) i 

Da uHCloscForWrire(gDataWriter): 

GlcJscCcimpon^ni ( gfJat aWr I tar): 
gDataWtitet w NULL: 

I 

// dispose of the data buffer 
if (gDar.aBuffer ! = NULL) 

DlsposcPt r(gDatsflufFer); 

// dispose of the mi it i nr descriptors 
if (gReudyaLafiCoraplcUonUPP !" NULL) 

DisposeDataJiCompletionUPPt gRoadDaiaHComp]otionUPP); 

if (gWriteDataHComp1etionUFP 1- NULL) 

DisposeDataHCompietionUPP(gWriteDataHCorapIetiotiUPP); 
gDoneTransferring ■ false: 

#|f TARGRT_OS_WTN 3 2 

// kill the tinier that tasks the data handlers 

KillTiltet{NULL, gTlmerlD): 

#endlf 

1 

QTl)U_Close Down Handlers simply closes the 
connections to the local and remote files and then closes the 
component instances of the data handlers. On Windows, it 
also removes the timer task that was calling 
QTApp^HandleEvent periodically. 

Listing M contains the complete definition of the 
QTDR_CopyReJiK>teFileToLocalFile function, which is called 
in response to the “Transfer Remote File.,/ menu item. 


Listing 14: Copying a remote file into a local file 

QTDR < )opy RetrnHcIHkTuLocainle 

OSKrr QTD^CDpyRp^otftFiUToLocalFlle 

(char *thftORL* FfiSpecPtr theFile) 


Handle myReattarRflf = NULL; //dam ref fin-the remote Ok 

Handle niyWrlterRef ” NULL; // data ref for the local file 

ComponentResult myErr “ badCompohentType j 

// tkielc the target local file, if it already exists; 

// if it doesn’t exist yet, well gel an error (fnltrr). which we just ignore 

FSpDelete(theFile): 

// create the local file with the iksired type and creator 

myErr = FSpCreaUUheFile* kTrannFi leCreator, 

kTrans PtleTypc. stnSy a t emS e ript); 

If (myErr 1= noErr) 
goto bail: 

// create data references for the remote file and the local file 

itiyReaderRef = QTDR MakeURLDataRef[theURL)j 
If (myReaderRef ^ NULL) 
goto bail; 

tnylfriterRef - QTDR_MakeFlleBataRfifCtheFile); 
if (myWriierRef — NULL) 
goto bail: 

// find and open the URI. and file <lata handlers 

gDataReader “ OpcoCorapononr(G#nDaraHandlftr(myReaderRef. 

URLDatallaitdlefSubType, krmr.aHCanRead)); 
if (gDataReader = NULL} 
goto bail: 

gDstaWritet “ OpenCamponent(GetDataHandler(rayWriterRef ( 
rA1iasTy pt*, kBataHCanWrite)); 
if (gDaLaWriter — NULL) 
goto bail; 

// set the data reference fur the UHL data handler 
myErr = DataHSetDataRef[gDataReader, rayReaderHef): 
if (jnyErr !“ noErr) 
goto bail; 

// set the data reference for the file dam handler 
myErr “ DataHSetDataftef(gUataWr3ter, myWrlUrltef); 
if (myErr t- noErr} 
goto bail: 

// allocate a data buffer the URL data handler copies data into this buffer, 

// anti the file data handler copies data out of it 

gUat&Buffer - Nev/FtrClear(kUataRufforSizc); 
myErr = HemError() : 
if (myErr != noErr) 
goto bail; 

// open a read-only path to the remote data reference 

myErr ~ ftataHQppnForRead(gDflTaReader); 

1 £ {myErr 1 = noErr) 
goto bail: 

// get die si/e of the reunite file 

myErr - DataHGet Fi 1 eS i z e (gU a ta Reader, h glly t esToTr a ns f e r); 
if (myErr 1= noErr} 
goto bail; 

// open a write-only path ic» the local tbua reference 

myErr = DataiiQpenforWrl l c (gl)-i t aWr J tor); 
if (rayErr ]= noErr) 

goto bail; 

// start reading and writing data 

gHnneTransferring *= false; 
gRytesTransferred “ OL: 

gReadDataliCompl^lionUPF “ 

NewDat all Comp let! tmUPP (QTDR_R e a d Do i a Comp loti onP roc); 
gWriteDataKCompietionUFF = 

NeuDataHCompiatloiiUPP (QTDR_WrIteDataCorapletioiiProc); 

// surt retrieving the data; we do tills by calling our own write completion routine, 
// pretending that we ve jtt?it siim-wfuliy finished w riting (I bytes of data 

QTDRJpfri l eDa taComp 1 ct I on P roc {gDa r aBuff er. OL. noErr); 


30 


Somewhere I'u. Fim> You 


MacTech • October 20(H) 









bail; 

// if we encountered any error, dose the data handler components 
if (myErr 1- noErr) 

QTDR_CloscDownilundlecs(); 

teturn((OSErr)myErr): 

) 


So we’ve manual lo use QuickTime's (fata handlers to provide 
a general-purpose network file-transfer capability that operates 
asynchronously, allowing us to play movies or perform other 
operations while the transfer ls underway, Of course, then.' are still 
some refinements we might add, such as alerting the user if he or 
.she decides to quit the application while a file transfer Ls in progress. 
Well leave these as exercises for the interested reader. 

Notice that we call the function DataHGetFdeSize to determine 
die size of the remote file (whidi is of course the number of bytes 
we need to transfer). f>ataHGetFileSize may need to read through 
die entire remote tile to determine its size, winch can sometimes 
slow tilings down (since we'it calling it synchmnonsly). Some data 
handlers (but not all) support die DatallGetFileSizeAsyTK- function, 
which allows us to gel this information asynchronously. You might 
try experimenting wiLh DataHCetFileSbcAsync to see if it improves 
performance in your particular situation. 

In that vein, you might be wondering: “sure, we can use 
QuickTime to transfer data ac ross the net, but is it any good? 
Whats the performance like? 1 " My preliminary (and admittedly 
unscientific) tests show that our code is in fact very gcxxJ. In a few 
sample FTP transfers, QTDatalfef consistently transferred files at 
least as fast as the latest version of Anarch ie, a popular shareware 
Internet file transfer application tor the Mac. Moreover, with a 
movie playing continuously in the foreground, QTDataRef took 
only about 10% longer to transfer the file. (And don't forget that 
our axle works on MacOS 8 and 9, Windows, and Mac OS X!) 

Data Reference Extensions 

Consider now this question: if we pass a handle data reference 
io die function GetGraphicsImporierForDataRef, how docs if figure 
out which graphics importer to open and return to us? Recall (from 
“Quick on the Draw” in MacTech, April 2000) that when we pass a 
file spa ification record to GetGraphicslnnpofterForFile, if first inspects 
die Macintosh file Lype (on Mac OS) and then the filename extension 
of die specified file. If neither of these inspections reveals the type 
of image data in the file, GelGraphicsImporterForRIe must then 
validate die file data (that is, look through the file data for dues to 
die image type). With a handle data reference, where there is no file 
type or filename extension, only the validation sLep is possible. 
Unfortunately, validation is time-consuming and, alas, not 
guaranteed to produce correct results. 

Quicklime 3.0 provided a preliminary solution to this 
problem by allowing us to attach a filename to the referring data 
of a handle data reference. (Let's call this a filenaming 
extension ) That is to say, a handle data reference is a handle to 
a 4 byte handle that is optionally followed by a Pascal string 
containing a filename. listing 15 defines the function 
GTDR_AddFilenamingExtension dun attaches a filename to the 


referring data of a handle data reference. 


Listing 15: Appending a filename to some referring data 

OTDR AddFitenam ingExTctraoii 

OSErr QTDR_AddFiienarainRExtensiDH (Handle tKeDataRcf. 

SlringFtr theFileName} 

I 

unsigned char myChar ■» 0; 

OSErr myErr " titiErr: 

If UheFIleName =“ NULL) 

rayErr - PtrAndHand (imyChar, theDataRef, aizeof (myCharU I 
else 

myErr “ PtrAndHand(thc*Fi leName, rhoDaiaRcf, 

IheFileNamelOl +1): 


retkjrn(myErr): 

J 


Tlie filename can contain an extension that provides an 
indication of die kind of data in the data reference turret, For 
distance, a filename of the form “mylmuge.bmp v indicates that the 
data consists of Windows bitmap dara. For reasons that will 
become clear in a few 7 moments, QTDR_AddFiIenamingRxrension 
looks to see whether theFiieName parameter is NULL; if it Ls, 
QTL>R„AddFiicnamingExlension appends a single byte whose 
value Ls 0, 

Quicklime 4,0 provides a more complete solution to this 
problem by allowing us to create data reference extensions for 
handle data references. A data reference extension is a block of 
data that is appended to the referring data, in pretty much the 
same way that we just appended a filename to that data. The 
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main difference is that, unlike the filenaming extension, a data 
reference extension is packaged as an atom, with an explicit 
type, QuickTime currently supports tour kinds of data reference 
extensions, defined by these constants: 


Q'lT)K_AcIdMIMETypeDiiiaRcfExtension function, defined in listing 
17, to add a MIME type as a data reference extension, (Be sure to 
add a filenaming extension before adding a MIME type data 
reference extension.) 


enim j 

kDataRefExtensionChokeSpeed ^ FOUR_CHAR_CODE(*chok'). 
kDat aRefExtensionMlHEType = FOUH_CHAR^_CQOE (* mi me'}, 

kDataRefExtensionHacOSFileType = FOUR_CHAR_CODE( f fLyp'). 
kDolaRGfExtennicinInitiali 2 ationData 


]; 


= FQUR_CHAR_CQDE(* data') 


A data reference extension of type 
k DataRelExtcnsionChokeSpeed can be added to a UHL data 
reference to specify a choke speed (whic h limits the data rate of a 
file streamed using HTTP streaming). Hie other three types can lie 
added to a handle data reference to help identify the kind of data in 
the target of the data reference or to supply some initialization data 
to the data handler* If a data reference extension is present, then the 
file naming extension must also lx.* present The filename can be 0- 
length, however, in which ease the filenaming extension consists 
only of a single byte whose value is 0. 

listing 16 shows how to add a Macintosh hie type as a data 
reference extension. 


Listing 17: Appending a MIME type data reference 
extension 

QTDR_AddM JMLTy pc Da LaKcflixtension 
OSEr r QTDR_AddM1METy p u Da LaR g fKx t en&ion 

(Handle thetlalaRef* StrlngFtr theHIMEType) 
l 

unsigned lonft royAtomlieader [2] ; 

OSErr rnyErr * naErr: 

if (LtieMTMEType — NULL) 
return(pacamErr): 

myAtomHeaderfO] - EndianU32_NioB(sizeof(foyAtomHeader) E 

LhcMlMETypefOl 1 1): 

tuyAtomHeaderfl] - EndianU32_NtoB( 

kDataRefExtetisionMTKEType): 

inyErr = PtrAndHaiH (myAfoinHeader, theDataRef, 

siznnf(myAtomHeader ))l 

if (myErr “ noErr) 

myErr “ FtrAndHand(theHIHETypG, LhcDataRef, 

theHiHEType[0] 4■ 1): 

return(myErr); 


listing 16: Appending a fde type data reference extension 

Q r rDR_AddMaO)SFncTypcDaUiRcfLxierisi<>)i 
OSErr QTDR_AddHatOSFi 1 t?TyptrOataRcfEKtenfiton 

(Handle LheDalaRcf, OSType theType) 

I 

unsigned long tnyAtomHeader(2] : 

OSType rayTypej 

OSErr wyErr - nulrr; 

myAtomHeader [ Gj = EiidianU32JttoB( 

sizeof (utyAtomlleader) + sizoftf (theType)): 
myAtomHeader [l] - EudlafiU32_NtqB( 

kDa taRefEjttensionMacOSFi leType): 

nayTypG ~ End LanU32_ NtoB (theType); 

tmyErr - FtrAndlhmd (wiyAtomHoader. ThfcDat.aRfcf, 

sizeof(myAtomHeader)); 

if (myErr = noErr) 

myErr = PtrAndHand{&myType. theDataKef, 

sizeonmyType)); 

refurn(my£rr): 


This axle simply culls FtrAndlland to append an atom header 
to the referring data and then calls PtrAndliand again to append 
the file type (suitably converted to big-endian formal). 

Another way to flag the type of data in a handle is by specifying 
a MIME type. MIME (for Multipurpose Internet Mail Extension) is a 
standard protocol for transmitting binary data across the Internet A 
MIME type is a text string used in MIME transmissions to indicate the 
type of [lie data 1 icing transmitted. (For instance, the .string 
“ video/quicktime’ 1 is the MJMK type of QuickTime movie Files.) 
MIME types can also be used locally to indicate die ly|x: of a File or 
other collection of data* Movie importers and graphics importers will 
look for MIME type data reference extensions to help identify the 
type of data specified by a handle data reference. If you arc building 
some movie or image data in memory, you can use die 


Conclusion 

As weVe seen, QuickTime uses data references to Find the data 
that its supposed to handle. Data references can lie embedded in 
movie hies or passed to Movie Toolbox and I CM functions. So 
whetlxjr we're building movies nr operating on l hem, understanding 
data references Is crucial to doing any real work with QuickTime. 
Here weVe learned how to work with data references to create 
reference movie hies, play movies from HAM, and open movies 
located remotely on the Internet, in the previous article, we also saw 
how to use data references to create shortcut movie files and 
embedded movies. In future articles, well work with data references 
as a normal part of our QuickTime programming. So it's good that 
we've taken rime to learn how to create and work with them. 

On the other Itand, data handlers are normally transparent to 
applications. We can use them directly for certain s[xx.ial purposes, 
such as transferring remote files to die local machine. But normally 
the QuickTime APIs insulate us from hiving to work with them al 
all. Typically, we can accomplish what we need by handing die 
Movie Toolbox or I CM a da la reference and letting it communicate 
with [he appropriate data handler. 

Credits and References 

I hanks are due lo Chris Flick and Scott Kuechle for 
reviewing this article and offering helpful commenLs, and to 
Peter Iloddie for providing some historical perspective. 

The official Apple documentation on data handlers can 
be found at http://developer.apple.com/techpubs/quicktime/qtdevdoG/ 
RM/rmDataHandlerComp,htm., 

See also http://developef.appla com/technotes/tn/tn 1195. h tml for another 
discussion of reference data extensions. fflS 
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You think the Internet is safe. 

Think again... 



NetBarrier. The first Internet 
security solution for Macintosh. 


m m m m mm 

I The|fjHl 

Internet security solution 



AIJ Mins connected lo the Internet (dialup, 
DSL, caldiMiiiHliin) are exposed to hackers, 
Whether you are a home user or a 
professional user, pur data interests them. 
That's why you need a security solution dial 
only Neiifcurier can provide. 

Personal Firewall 

NetBarrier protects and monitors all 
incoming and outgoing data. A customized 
mode allows you to create y our own 
defense rules, thereby ottering the most 
secure level of protection. 


Antivandal 

NetBarrier blocks all attempts to break 
into your Mac, detects wrong passwords 
and logs vandal attacks lor complete 
protection. Moreover, it has an alarm to 
inform you of every intrusion attempt. 

Internet filter 

NetBarrier analyzes data as it leaves your 
computer and prevents unauthorized 
exporting of private information such as 
credit card numbers, passwords, sensitive 
data and more.,. 


©DEPOT 
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WEBOBJECTS 


By Patrick Taylor and Sam Krishna 


How to build an EOModel 
(or look just like one) 


Back in 1996, there wasn't much competition for 
WebQbjecis. Nowadays however there are dozens of weh 
application servers on the market, each promising that tlieir 
package will make it oh-so-casy to publish data from your 
relational database to the World Wide Web. 

If you picked some other web application server you 
generally had a choice of two solutions: tying yourself to a single 
vendor's database package (the “simple* solution ) or embedding 
SQL into your page template (the not-so "simple” solution). If 
writing SQL is your idea of a fun Friday night or if you don’t 
believe that object-oriented classes are a spectacular 
improvement over SQL., then you probably won’t fully 
appreciate EOFs special charms. But even if you aren't 100% 
sold on the Enterprise Objects Framework, the sexy EOModeler 
application might still turn your head, 

EOMt Kiel e w c >ne cApple' s WebO I ejects devel t >pm e n t i<x>ls, 
provides you with a simple way to manage a great deal of the 
complexity associated with databases. EOModeler lets you 
graphically design your object data model 

In EOModel, you replace some of your relational database 
terminology with object-oriented ones. However, the concepts 
map quite neatly. 

EOEntity 

An F.O Entity represents an actual class in an object model, 
one which generally stands for a table in a database. 
Fundamentally, though, an EOEntity represents some piece of 
information or data that must lx j captured and represented in 
your application. 

EOAitkibute 

An EOAtiribute represents a column of data in a database 
table, EOEntities are composed of EOAtiributes. An EX)Attribute 
has two intrinsic data types: a class type and an external type. 
The class type represents the object type (like a java. king. Si ring 
or an NSString) that the attribute will be as an enterprise object's 
(EG) instance variable. The external type represents the kind of 
database type (like a VARCHAR) that die attribute will l)e stored 
as in tlie database. 


How to nuiLO an EOModel (or look just like onsO 


EORftationship 

An EORelalionship represents a relationship between two 
EOEntities. There are two fundamental types of relationships: to- 
one and tomany. What this means is that an EG can have cither 
a to-one relationship to a single EO of a particular type or a to- 
many relationship to potentially various EOs of a particular rype. 
A few variations on both of these fundamental types exists: 
many-to-many (where an KO can have a relationship to many 
F.Os of a different type, and EOs of the different type can have 
multiple relationships back to the original type of EOs), reflexive 
to-one (where an EO has a relationship back lo another EO of 
the same type) and reflexive muny-tu-many (where an EO can 
have Lo-many relationships back to other EOs of the same type). 
We will only be covering regular to-one, to-many, and. of course, 
many-tomany relationships in this article. 

EOEntities are Composed of EOAtiributes and Connected 
to Other EOEntities Through EO Relations hips 

EOModeler provides a Wizard tliat can generate an EOModel 
fmm a pre-existing database saving you from much of the effort of 
recreating an object intxle] from scratch. How complete die object 
model representation of the underlying daiulxisc is depends on the 
adaptor and the database, some adaptors like ODBC provide only' 
basic information like entities and attributes, but not relationships or 
other database-specific features. You will need to manually modify 
the EOModel to provide the necessary missing features. 

If you're familiar with Microsoft Access* graphical modeling 
tools, you will rather quickly pick up on the graphical modeling 
mode in EOModel. You aren’i limited however to viewing data 
flows graphically, EOModeler provides developers with two 
other view's: an outline view and a class browser view.You can 
view additional information alxjut an EOEntity, EO Attribute or 
EOReiaLions!lip with an Inspector. 

One interesting tiling alxxit EOModeler is that it isn't a one¬ 
way only tod, it can generate SQL to create a database from an 
EOModel For instance you could generate an EOModel from a 
MSAccess database and then generate the SQL necessary to 
recreate the database structure in Oracle 8i. Or you could design 
your object model from scratch in EOModeler and then using the 
SQL generator build a database structure. Through its adaptors, 
WebObjeets/EOE provides developers with a remarkable degree of 
database independence. 
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An Example Application: ProjectManager 

To truly understand EOModder it helps to see it work in 
an application. ProjeetManager* our example application, is 
intended Lo assist a Project Manager in allocating resources For 
the various projects that he or she manages in a company. 
One way of describing the entities would be: 

Employees 

Projects 

Departments 

Managers 

Real-life Project Managers reading this article will see that 
we've simplified the nmnl>er of entities that normally participate 
in a real project model I lowever t we can simplify this model even 
further when we realize that Manager is just a different type of 
employee and does not need to be its own entity, Further 
simplified die current set of entities are: 

Employees 

Projects 

Departments 


Access, Sigh 

There are several very good reasons tor using MS Access in your 
WebOfcjeets application. It is omniproem, practically war business 
has an Access database. It is cheap especially if you already own MS 
Office Professional for W indows It is easier to create a database with 
it than with many other RDBMS. 

However, you are likely to run into some problems when using 
Access with WcbOhjccts. You need to ensure that you’re using a very 
recent version of the ODBC drivers. In earlier versions of Access, we 
had problems with Aulonumbcr in applications which weren’t read¬ 
only Unlike other RDBMS* Access only passes a bare minimum of 
information to the EOModder Wizard and only accepts a bare 
minimum from EO Modeled* SQL generating feature. 

This isn't to say that you Shouldn't use MS Access (well . r ) 
but it probably won't be simpler than Frombase or Openbase 
because you won i have full access to all the features and 
automation available through EOModder. 0O 


Having identified the entities in this application, we need to 
make them usable within the ProjectManager object model. 
Entities are named using the singular form: 

Employee 

Project 

Department 

Singular form is used in order Lo simplify and rationalize the 
naming of relationships. You w ill later need to use tile plural 
Form, so its easier in name entities in singular Form rather than 
try to figure out: "What is the plural form of "Employees?” 

flic next thing we do is create the entities in the EQModel 
Generally, we have to define three things in order to create an 
EOEntity: the entity name, the table name, and the class name. 


EOModder* default behaviour is io assign any EOEntity's 
class name to EOGenericRecord, which is simply a data object 
that can be used to manipulate an EGs data without going to the 
trouble of defining a class or class behavior In this case well 
give the Employee entity the class name Employee. 


En tity [Name Tabic Name _ Class Nam e 

Employee EMPLOYEE_Employee 


Common practice in EO Modeling is to borrow the database 
convention of naming tables and columns with all upper case 
characters. While it isn't necessary to maintain Lite same names, 
the entity, table and class names are the same for this example. 

Once weVe finished filling out the required information 
for the EOEntity, we can start defining the EO Attributes we 
want to track in each EOEntity. In the Employee entity, we 
want to track certain things: 

First Name 

Last Name 

Employee Number 

Address 

Salary 

Department 

Manager 

Start Date 

Title 



Download full featured evolution version 


Ocrom:R 2000 * MacTech 





























Here's how we model that information: 

Employee Entity 

first Name 

last Name 

enipk jyue Number 

employeelD 

street AddressOne 

street Add ressTwt) 

city 

state 

zipCode 

salary 

departmenrlD 
sian Dale 
title 


You’ll notice some things righl off. First, the Attributes 


Naming 

Naming in an Object Model is probably the most Important thing a 
WeliOhjects developer can do. If entities, attributes, and relatioftsliips arc 
named wdl, a developer can develop and debug so much faster than if 
elements arc improperly named 

Some common problems that occur in bad object modeling: 

1) Poorly named or misnamed entities 

2) Abbreviated names of entities 

3) Abbreviated names of attributes 

4) Misnamed attributes 

5) Misnamed relationships 

if you can at all avoid them, abbreviations that aren't pan of the 
common vocabulary (like ID) shouldn't appear in your EOModtd, Wdf 
named eniiiies, attributes, and relationships make life easier for the 
developer—so much so that applications that take months to develop 
could shave several weeks off with strong naming Good naming Ls 
particularly important if you share responsibility for an application with 
other developers or it someone cLsc may someday inherit your code. 1E2 


start off lower case but are intercapped since spaces ureiVi 
used between words,The names arc descriptive to assist in 
recognition. You can name entities with acronyms or 
nonsensical names, but you Ye only punishing yourself You’ll 
also notice that there isn't always a one-to-one mapping 
between the identified items and the actual entity. 

For our application, Address is more complex than what 
can lie represented usefully in a single attribute — because 
of certain postal conventions, modeling it usefully requires 
that we use several smaller attributes, like streetAddressOne, 
streetAddressTwo, etc. (these address rules apply in the 


United States but may differ in other countries). You will also 
notice that the employee's department only appears as a 
department ID. We have a depart mend D instead of actual 
department attributes because in our application the 
employee's department information is actually a relationship 
that an Employee has with a Department. There are two 
reasons for choosing this: it conserves resources by storing 
an ID (32 or 64 bits long) rather than multiple potentially 
redundant entries (16 bits per Unicode character). 

When you model a particular attribute, you need to define: 

attribute naiue 
attribute class value 
attribute external type 
attribute column name 

attribute width (if ridbmig an attribute that tracks a string object) 

We also define whether or not an attribute is a class 
property. Class properties are identified with a small 
diamond to the left hand side of the attribute name. When 
attributes are identified as class properties they can be 
manipulated in code. Attributes that ate not marked as class 
properties are handled automatically by the EOF subsystem. 

A word on class properties; any primary or foreign keys 
should not be marked as class properties (ie missing the small 
diamond). The EOF' subsystem should manage any primary or 
foreign keys automatically. This way a lot of the magic of EOF 
is used to dual with key generation with the database. 

After all the attributes are defined the EOEntity should 
look like this; 
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EOReiationships 

EOReiattonships represent relationships from one EO to 
another F,G (or groups of EOs). There are two fundamental 
types of relationships: to-one and to-many. Since our mythical 
company only assigns employees to a single department, 
Employee should have a to-one relationship to Department, 
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Rfauty-Rasfi> Object Modeling 

A well-named object mode! will do neither a 
developer nor a client any good if die object model 
does not represent the reality of a business domain as 
accurately as possible. 

IJrtfiwTunatdy there aren’t a kit of positive indicators 
for how reality'based an object n>odd Ls. However there is 
si scl of negatives you can watch out for, 

1) Primary or foreign keys are class properties 

'ITiere should never be a reast>n for this. This is 
probably Lhe number one reason why object models in 
WcbObjccts get excessively complex and become 
difficult to maintain. 

2) Excessively deep nelatioasbip padis 

An example of this would be traversing this kind of 
relationship chain: 

Hustemd*>Wifi&>Sistcr>Mother->Brother when all 
you're looking for Ls: 

Husband->We->l Inde 

POor models will have an excessively deep 
relationship graplr for a simple piece of information, 

3) Entire toone relationship ;trc flattened into a table 

For example, if a Project was limited to only two 
employees per project, you miglil see a Project poorly 7 
modeled like this: 

Project 

name 

dieniNamc 

cmpkiyecOncFirstNanie 
employeeOnel^stNamc 
empk iveeTwoFirsLNJamc 
cmployeeTwoUistName 

When you start seeing a lot of duplication of data 
between tables, it may be rime to create a relationship. 

4 } Excessively diffictilt-tLKxplain-or-name tdatkmsbips 
and eniities 

Tliis is a little harder to describe, but you'll probably 
know it when you see it. For example, you may see or 
create an EOEmity dial you cannot name well alter 
dunking about it for 20-30 minutes. Or you may create a 
Join Entity 7 that has a to-many relationship to a third entity 
that neither of the entities on either side of the many-to- 
nsany relationship needs. 

Tliis list is by no means complete but keeping drese 
factors in mind shouid help you in the always difficult task 
of modeling Keep practicing at it: a wdl-strucmred and 
accurate Object Model with a strong naming convention is 
worth its weight in gold. Good luck. IQ 
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Our mythical company lias multiple employees in each 
department so Department will have an inverse UMiiany 
relationship back to Employee. 



Department and Project entities mast track the following 
types of information; 

Department 

name 

budget 

Project 

name 

clientName 


Here are pictures of the Fully modeled Department and 
Project entities without relationships; 
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Employees aren't limited to working on a single 
project and each project will tend to have several 
employees assigned to it. Because of this we need to 
create a more complex type of relationship between 
Project and Employee than those we’ve discussed* The 
type of relationship that represents these complex 
systems is called a 44 many-to many" relationship. 
Unlike to-One and to-Many relations hips, Many-lo- 
Many relationships can't be represented just by an 
EG Relationship* 

What is required to create a Many-lo-Many 
relationships is a Join Entity’* A Join Entity is a special 
type of EOEntiiy that links two entities to each other in 
a many-to-many relationship* The Join Entity stores the 
Primary Keys For each of the two joined entities* 
Following common practice, we ll name the join entity 
EmployeeProject to show its place in the relationship 
between Employee and Project. 

EmployeeProject will only have two attributes and 
two relationships* The two attributes will be 
employee!D and project! D r respectively* The Lwo 
relationships will be named employee and project, 
respectively* Here is what the fully modeled 
EmployeeProject join entity looks like: 
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Shortcut! 

There Is a short nit in EO Modeler which simplifies the 
crention of nwny-to-muny relationships. Here are [he steps to 
the shortcut: 

1) Select the two entities you wish to join 

2) Select front the Properties menu, Join in Many-to-Many 
relationship* or select the Many-to-Many icon on the toolbar 

After the Join Entity has been created, you will need to fill 
in the table name and the attributes’ column names. Ii will look 
something like this: 




Once modeling is complete, here is a diagram of what your 
model should look like with entities, attributes, and 
relationships: 



You have now built an object-relational model without 
writing n single line of code. No SQL was needed and. for the 
most pan, you could use any database you wanted. The 
database portion is often the most difficult and painful pan of 
the development process. H53 
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PROGRAMMING 

TECHNIQUES 


By Kas Thomas 


How to Harness the Power of 
Associative Arrays 


A widely underutilized 
technique can go a long 
way toward making your 
code smaller, more reliable, 
and easier to maintain, 
whether you program in Q 
Java, or JavaScript 

Postering reliability, maintainability, 
compactness, and good performance in 
code has been a const a ni quest for 
programmers and language designers over 
the years. It's rare that one technique can 
give you all of the above benefits, 
concurrently. But intelligent use of 
associative arrays can do that, If you 
haven't yet tapped into the power of 
associative arrays, you might want to give 
the issues involved some thought. The 
issues are widely applicable to a variety of 
programming tasks, cutting across all 
major languages. 

One thing's for sure, if you use a lot 
of switch statements in your code (to “case 
out” user-selected actions, for example), 
you're sitting on a great opportunity to 
improve the reliability and maintainability 
of your code; jusL follow along and see. 

What Is an Associative Array? 

An associative array is a collection of 
data values in which access to any 
particular value is obtained via a (single) 
key. Generally speaking, it s a one-to-one 


mapping of data entities (“values”) Lo keys, such that no two 
values map to the same key (although two different keys could, 
coincidentally, contain the same value). For example, in an array 
of TV listings, you might very' well find that two different 
channels are showing the same episode of GilligaiYs Island at 
4:00 a,m. Tuesday, but you would never had Channel 2 listed 
twice, showing two different shows in the same time slot. 

In a larger sense, associative-array mapping is an application 
of set theory, and languages that have a robust collections 
package will invariably implement some form of associative- 
array mapping. 

For a quick example of an associative array, consider the 
hypothetical entity in Figure 1. 



Keys Values 

Figure I. A h)pttibetkal assocktiin* array. 

In this example, we have an anonymous (nameless) array of 
tuples shown as keys mapped to values. The iremlype key, for 


Kas Thomas lias been programming in C and assembly on the Mac platform since More Windows existed. By day. he is a 
Senior Technical Writer for Silvemream Software (a maker of a pp-server soft war. You can reach him in care of 
editorial@macleth com. 
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example, maps to the value 4 auu)\ If this were a conventional 
(ordered) array, we would say that the zeroth item in the array 
is the (string) value *auio\ the first item is ‘ \WD\ etc. 

For the array shown in Figure l to Ik useful, we need to be 
able to hold a reference to die array in a variable, and we need 
to have a syntax lor obtaining the value of each member, given 
tile value of the corresponding key. It would also lie nice if we 
could find out how many items are in the array {since it might 
lx arbitrarily large) and to know how to iterate through the 
members. With an ordered array, you can step through the 
memlxTs in sequence. But in an array like this one, where the 
keys aren't integers, how do you enumerate the array's contents? 

Associative Arrays in JavaScript 

Core JavaScript (or FCMASeript) has a convenient syntax for 
dealing with constructions such as this. (Even if you’re not a 
JavaScript programmer, liear with me here, because 1 11 be 
discussing other languages in a moment.) In the world of object- 
oriented programming, an arbitrary collection of data entities is 
often called an object. In JavaScript, a generic object is, in fact, 
an associative array (whose members can be references to 
functions, in which ease those particular members are called 
methods). In the OOP world, dot notation is commonly used to 
“index into" an object. For example: 

var myObject - new Object(); 
myQbjOct.itemType - *auto*: 

myObjecU subtypft &< 4W!p*; 
nyObjeet.make “ 'Jeep': 

rayQbject«year * '1998'; 

tnyOb j ec t * cole r = ' green *; 


In JavaScript, this is an entirely acceptable way to 
implement the abject suggested by Figure 1* An equivalent 
syntax that uses literal notation is: 

var JnyObjeet * f 'iteniType 1 : *atito H . 

'subtype* : *4Vn', 

'make' i 'Jeep*. 

"year* i M998\ 

* color* ; * green* ); 


But are we justified in calling tills an associative array? Yes, 
we are, Ixxnuse it turns out we can also use array notation 
(square brackets) in JavaScript to refer to object properties: 

var rayObject = new Object0: 
myObiect 1'iternType'] = "auto 8 : 
myObject[‘subtype*j = ‘; 

tnyOb jfirt f* make 1 j * * Jeep *; 

myObject byear* ] = ‘1998*; 

myObject[*color*1 = 'green'; 

if (rcyGbj eel [ H it einType ‘1 *= * auto * 

&& myObject[*make'] — 'Jeep') //true 

myObject [ * subtype 1 1 * * 4WD *: // assign l - i WD‘ to myt)hjfct.subtypc 

In JavaScript, square brackets can substitute for dot notation 
when referring to object properties. The only proviso is, the 
enclosed property name must be supplied as a string literal (as 
shown above). Minis turns out to lie an extremely handy 
syntactical construct, Ixxause it means we are not limited toone- 
word property names* We can now consider constructions like; 

myObject [ 'extended warranty*] “ true: // k-gj| 
myObject ['original delivery date*] = ‘1/1/98*; // legal 
myObject,'original delivery date* * *1/1/98'; // FRROIC 
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Iterating Li trough the contents of an associative array (or the 
properties of an object) would seem to present a problem, since 
the contents aren’t necessarily ordered and can t be “indexed 
into" numerically. In JavaScript, however, there is a very' handy 
loop syntax for doing this: 

var bigstring - nev Stringf): 

for (var i in myObjeet) 
bigstring +" t + m \n m ; 

Tire alx>ve code builds a list of all the property names in 
my Object (separated by newlines), concatenating them into a 
single big string. 

Pfrl 

Perl has a built-in associative-array construct called the 
hash. The syntax lor creating a hash Icxiks like: 

%jnyObject = ('item'fype* , 'auto*, 

'subtype' , *4WD‘, 

"make* * ’Jeep** 

'year’ , *1998** 

*color* , * green’J; 

Notice that commas are used throughout the pairs list, 
rather than the more readable JavaScript technique of putting 
colons between keys and values (using commas to separate 
complete tuples). 

To access a hash value in Perl, you use a notation that 
looks like: 

SmyObjectJ ’color' I * *red*: 

Notice tile seemingly inconsistent use of the dollar sign 
(instead of die percent sign) and curly braces (instead of 
parentheses) for accessing individual values of a hash. This 
is a standard Peri idiom. The percent sign refers only to 
complete hushes. 

Java 

With the advent of the Java 2 platform , the javaaitil package 
now has a powerful Collections Framework (not to lx* confused 
with JGU the Generic Collections library for Java by ObjectSpace, 
which was first to-market and was widely distributed in IDEs before 
Sun came out with theJSE Collections Framework), encompassing 
sorted and unsorted sets, maps, and lists, plus iterators for same, in 
(Jm.'ad-safe and non-thread-safe versions. Prior to Java 2, the 
language had Vector and HashTable classes to accommodate this 
need, but those classes have lxx*n relegated to legacy status. Today, 
if you need an associative array, you call on the HashMup class, 
which implements the Map interface: 

Map map - nrw Hu^bKapO : 
map.put(“1 tctiiType”. “auto**); 
map,put(“subtype* * “4HD"); 
map.put{“make" , ; 

map. put [“year*' . "1998"); 

map.put("color M , “green"); 

For sorted maps, you can create a TreeMap (using a Map us 
input, if necessary), which stores its elements in an always- 
balanced tree. 

Now to I Iaknf.ss tup Power of Associative Arrays 


C AIND C++ 

In C++, the Standard Template Library provides rich support 
for collections idioms of all kinds, the map is an associative 
container that accomplishes die kind of functionality we’ve l>een 
talking about: 

map(string.string) myMap: 

ntyKap [" 1 Lemlype** J = "auto": 
months["subtype”! ~ “4WIT; 

//ctc.eic, 

To use it, be sure to ^include <map>. See any gcxxi 
reference on STL for further deLails. 

ANSI C, on the other hand, has no built-in support for 
associative arrays. You can craft your own support, of course, 
with a little effort. But how? As you might guess from the 
repealed use of the strange term "hash" in this context, 
implementing an associative array from scratch requires the use 
of hash techniques. 

What, exactly, is a hash? A hash is basically a mathematical 
function in the canonical sense: a "black box" that maps domain 
values to range values, with the requirement that any one 
domain value can map to no more than one range value. This Is 
exactly the mapping behavior we re looking for, of course. 

But what does a hash function really look like? The answer 
Is, it can look like whatever you want it to kx>k like, or (more 
commonly) whatever you need ii to look like, If that sounds a 
bit vague, that’s because hash techniques hill into a curious 
category of computational heuristics with a long background in 
computer-science lore. In the old days of limited machine 
resources, you’d use hash techniques lo maximize performance 
while minimizing storage requirements. Good hash functions 
weren’t often published, and if they were, their workings were 
rarely self-evident 

A Hash-Code Example 

A quick example may help. Suppose you are implementing 
an exception dictionary for a spellchecker: i.e,, a special 
dictionary to store user-entered words. What you want is that 
when a user types a word that is not in the regular dictionary, 
the exception dictionary can lx: consulted; and at that point, you 
simply need in know whether the word exists in that dictionary. 
(If not, you Hag lite word as a possible misspelling and notify 
the user.) You have a maximum of 5 Kbytes of storage available 
for this task, because you’re running on a 1970s machine with 
severely limited resources. 

A typical answer to Lhis challenge would l>e to insert 
exception words into a linked list, and do a lookup by traversing 
the list. Will] 5K of storage and an average word length of live 
characters, you could store as many as i T (XX) words in the list 
(more than adequate for most exception dictionaries), Bui 
lookups will be time-proportional to the number of words in the 
list, and there will be significant overhead in terms of list 
management, because each time a new word is entered in the 
list, you have to lx 3 sure it doesn’t already exist. 
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This approach gets a 1) for ingenuity. 

A bright young programmer in your department comes to 
you at litis point and says “Wait! I have a better idea." He 
explains that if you keep the linked list sorted alphabetically, 
you can speed lookups because they will occur in timc- 
proporricin to the log of tlic number of entries. list-maintenance 
over!lead is reduced us well, although storage requirements 
haven't changed 

This represents a significant improvement. Let's give it a O 
(or maybe even a C++) for effort. 

At this point, a consultant walks in the door anti offers u> 
solve the problem for you in such a way that up to 40,000 words 
can l>e stored in your exception dictionary and lookups are 
instantaneous, with zero table maintenance. You say 10 him 
“Thank you, but that 's dearly impossible. Don't leL the doorknob 
hit you in Lhc butt on the way out" He goes straight to your 
competitor, implements the solution, and eventually the 
competitor puts you our of business. You end up face-down in 
the gutter, next to an empty ixXtle of Ripple. 

How did the consultant do it? first of all. since you are only 
concerned with whether a given wort! has an enLry (true) in the 
dictionary or not (false), you're really looking for a binary 
(Boolean) answer to a question; hence your 5K dictionary can 
really store 40K lookups (assuming 8-hit bytes, of course). The 
dictionary needs to l>e implemented as a bit table. 

To implement a direct lookup of words, we resort to the 
following heuristic. To store a word in the dictionary, we submit 
the word string to a hash function, which in turn converts the 
word from a siring to a numlxn* in the range of zero to 5K- 
ininus-one. We then index into the bit table at the offset thus 
obtained, and store the word by flipping the bit *on. M (A zero bit 
means the word doesn't exisl in the table.) To look up a word 
and see if it exists in the exception dictionary, we simple hash 
the word and do a direct Itxikup. If the entry in the table at that 
lookup Ls true, the word exists. If not. it doesn't. Problem solved. 

Finally, an A+ solution! 

Hash Functions 

But we still haven't resolved the question of what a hash 
function looks like. Earlier we merely said that it could look like 
w hatever it needs to look like. Let's take the except ion-dictionary 
example we just discussed. I low many biis worth of information 
does a ^-character string really hold? If the string represents an 
English word, each character can have one of 26 possible values 
(except that the first character am lx* upper or lower case; hence 
52 possible values). Storing 26 possibilities requires 4.7 bits: 52 
possibilities requires 5,7 bits. Hie average word therefore requires 
5.7 + 4 ■ 4.7 == just under 25 bits of bandwidth. Every 5-character 
English word can therefore lx: converted (mapped directly and 
unambiguously) to a 25-bit numlier. Which Ls to say ? a number 
between zero and 53,554,431. 

Clearly, if we had 32 million biLs ( i megabytes) of storage 
available, and words could never be longer than five characters, 
you could convert words directly to binary numbers and use the 
numbers as offsets into a bli table. 
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Unfortunately, in the real world, words art* not constrained 
to Five characters in length and four megabytes of table storage 
are not always available. In fact, our example calls for no more 
than 5 Kbytes (4QKbits) of storage* 

Why not take the bottom 15 bits of each word (discarding 
the rest) and use Lhai as an index into a 40Kbtt table? '(Tie answer 
should be obvious. Words often have the same endings. Taking 
the last 15 bits of ‘eating’ and ‘drinking’ would result in fxnh 
words contending for the same spot in the exception dictionary. 
Totally unsatisfactory* 

The crux of understanding how a hash solution works in 
this kind of situation is to think long and carefully about the 
problem. IF you think about it, you will realize that the ASCII 
values in words are not at all randomly chosen* The 
composition of word strings in English is constrained by 
spelling rules, which in turn are determined, in pan, by 
constraints on the speakability of syllables (he., the geometry 
of the human voice apparatus). The average English word may 
consume only 25 bits of bandwidth, but there most certainly 
are not 52 million different 5-letler words in the English 
language! ITie actual number of different 5-letter words you 
might encounter might only be in the Sow thousands. 
Certainly, in a spellchecker context, 5* letter “exception" words 
(words that are not commonly found in English) would likely 
he numbered in the low hundreds, if that many. 

Careful analysis of the problem space should convince you 
that what we’re really dealing with here is a sparse data set. We 
will be mapping a few hundred exceptions (or at most, a few 
thousand) into a 10,000-bit table. All we need is a way to convert 
words to numbers that map well across rhe available domain. 

Suppose we design a hash function in C as shown in Listing 
l (where ch is a pointer to the word string), 

fisting 1: hash() 

hiisho 

unsigned int hash(ch) [ 

unsigned lot hash value “ 0; 
i f (1 * eh) return 0: //suniiy 
do I 

hashvalue +* "ch+’h 
hashvalue *• 13: 

) while (*ch); 

return (hashvalue \ TABLESIZE); 

I 

This hash function adds the ASCII value of each character 
in the string, one by one, to a temporary variable. But in 
between each addition, the variable is multiplied by the magic 
number 13, which (in binary terms) is equivalent to a left-shift 
by log(13) bits. (Prove to yourself that this is so.) What's the 
significance of 13? Nothing. Il simply works. Might some other 
number work better? Yes! That’s die magic of hash functions. 
Often, you can "tune” them to make them work better. 


How TO I iAHNESS THE POWER OF ASSOCIATIVE ARRAYS 


What does “work better” mean? It means you have fewer 
situations where two different character strings hash to the 
same numeric value. When two data objects hash to the same 
value, it’s called a hash collision* Collisions are usually 
undesirable. In our exception-dietionary example, it could 
mean that a nonsense word maps to the same dictionary 
location as a perfectly valid word! 

Dealing with Collisions 

'there are various ways of handling collisions. The most 
common w r ay (not for bit tables, but for tables where actual 
string information might be stored) is to fork a linked-List node 
at the point of the collision. Another method is to keep parallel 
tables, but with different hash functions for each. An “entry" in 
the dictionary would actually consist of an entry in each table* A 
lookup would verify that Hash 1 produces a positive result from 
Table 1 and Hash 2 yields a positive result from Table 2. Prove 
to yourself that (given suitably designed hash functions) if a 
collision happens in the first hash table, it’s extremely unlikely 
that a collision also occurs, simultaneously, in the oilier hash 
table; therefore, the overall collision rate is the product of two 
small numlxrs (l_hc individual failure rates of the hashes). 

In some situations, collisions can safely be ignored; the 
“collider” overwrites the old table entry, and that’s that. This can 
actually be desirable in instances where data entities are 
expected to regularly go out of scope. On this case, you have 
what is commonly known as a "weak’ 1 associative array)* In the 
spellchecker example, it’s debatable whether collisions are 
important. No spellchecker is ever perfect. If the odds of a 
misspelled word hashing to the same sjxrt as a legitimate word 
are less than, say, one in five thousand, would the user really 
notice? Would he care? 

Hash Tuning 

The fascinating tiling about hash functions like the one 
above is dial they can lx: tuned for better collision performance 
(lower collision rates)* What makes this fascinating is die fact 
ihot, because the problem is so poorly defined (mathematically), 
an analytical solution is usually out of the question. Ilierefore, 
tuning must be done empirically: try a tweak, measure the result. 
Try another tweak; measure the result. Repeat until happy* 

You might want to write a short program that takes a text 
stream (a document) as input and maps the "vocabulary" to a 
hash table, measuring collision rates in the process. Find out 
how collision rate varies with load factor (table consumption) for 
a given hash function. Then try changing the function in some 
way, and see how the collision performance changes. 

Fhe example hash function given in Listing 1 is actually 
a surprisingly gcxxl hash function for most purposes. With a 
driver program (such as Hash Mule; see further below), you 
can prove to yourself, empirically, that this modest-looking 
function works much better (i,e,, produces many fewer 
collisions) than the same function with the number 12 
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substituted for the number 13^ (This is why I called 13 a 
magic number) In fact, when 1 ran a quick test of Listing t 
using the Declaration of Independence as the source text 
(hashed into a table will i room for 1024 words), I found that 
changing the magic number 13 to 12 caused collisions to 
more than double. 

In general, even numbers produce poor results, and non- 
prime odd numbers ( while better) are not as good as primes. 

When writing a hash function, you will always need to 
constrain the final output to a certain range (in our example, 
5KX Be aware that, for tuning purposes, it can matter a great 
deal what the "modulo” constraint is. Again, it mrns out that 
a prime number here will improve performance. So make 
your lookup table an odd size! (But don’t take my word for 
it. Write a test program and prove it to yourself.) 

A Common Hash Misconqction 

A common misconception is that hash functions are 
designed to distribute values randomly over a given 
range. You should convince yourself that this is not true. 
After all, if hashing were this easy, every hash function 
would simply return a random number (converted to 
integer form and scaled to fit the desired range). The ideal 
hash function is usually one that distributes keys evenly 
across a range, with no collisions. Random numbers tend 
to cause collisions, at a rate equivalent to the hash table 
load factor. (Thai is, when the lookup table gets half full, 
each new entry into the table has a 50:50 chance of 
generating a collision.) A good hash function can do 
much better, because hash functions can be constructed 
to remap data non-randomly. And in fact, this is exactly 
what you are trying to achieve. You are trying to map a 
sparse, non-random data set to non-random locations in a 
table: locations that spread out evenly and don’t overlap. 
If you know a tiling or two about the data before you 
begin, you can make intelligent decisions about how to 
craft the hash function. 

Consider a list of 500 arbitrarily chosen unique words 
selected from Webster's dictionary at random. Imagine thaL 
you are trying to map these words into a hash table that 
has enough space for all 500 words, but only enough 
space. (But you don't necessarily know in advance how 
many words there are.) Can it be done? Of course. You just 
need to develop a hash function that maps table positions 
to the words’ alphabetical ranking. If you can analyze the 
word list in advance, this is a piece of cake. If you don’t 
have advance access to the words, but your hash object is 
free to reorder table data on the fly, again it's not a hard 
problem, because you can insert words in alphabetical 
order and reorder as necessary. Even if you know nothing 
about the words (except that they are words!), you can 
easily come up with a hash function that does a better job 
of mapping them Lo a table (i.e., with fewer collisions) than 
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mere random dart-throwing. 

There's no magic procedure for constructing a good 
hash function. Eadi situation is different- What might be 
a great function for one set of conditions could very well 
be terrible under another set of conditions. The trick is to 
understand your data set (and what's unique about it) and 
understand what it is you are trying to do: map members 
of the set onto intervals that don't overlap. 

Putting Associative Arrays to Work 

With a hash function approach in C, we haven’t quite 
achieved the iablefstringl lookup ease of other 
languages, hut we've approached it quite closely, because 
we can instead do: 

lookup - tablet hash(’myltem') ]; 

But the greater question, at this point is: How can you 
put associative arrays to work? One example is well- 
known: In compilers, symbol tables are usually accessed 
via a hash function that computes a likely place to begin 
a serial search. Since symbol-table lookup is a very 
frequent occurrence in compilers, the performance of the 
hash function (both in raw execution speed and in 
collision rate) can have a dramatic effect on overall 
compiler performance. 

But what if you’re not a compiler writer? In that case, 
you might want to consider a possible application that 
applies broadly across a variety of programming tasks in 
a variety of languages. Ii involves case 1 statements. 

The Case Against Case Statements 

Most high-level languages support a switch construct 
that allows options to be associated with desired actions. 
In C: 

switch( option ) t 

case 0PTT0N_A : do_Bonu?t hingf) : 
break: 

case QFT10H_B t 

case 0FTIGN_C r do„something_else(J; 
break; 

// ... more options processing 

derau 1 l : rlo_wha L ever () : 

I 

Usually, ihe cases must refer to hard-coded values. 
Fall-through occurs by default, which means that if you 
leave a break statement out (such as with OFTION_B 
above), execution continues with the next case. The 
original intent of the switch construct was to keep 
programmers from having to resort to long chains of 
if/else actions (while leaving code readable). But 
hindsight has shown switch/case syntax to be a 
notably poor syntax design in a number of respects. 
First of all, it doesn’t save any typing (over if/else 
actions). In fact, switch blocks are usually quite long, 
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because in instances where there are only a couple of 
cases, programmers tend to collapse everything to a 
few if/elses. Ihe opportunity for typos is high in long 
code blocks. Also, the default fa 11 -through behavior of 
switches is known to be a bad design decision, 
because it's not the default behavior most 
programmers are looking for, most of the time. (Some 
years ago. Sun analyzed its C compiler source code to 
see how often the default fall-through path was 
actually used. It turned out the Sun ANSI C compiler’s 
front end had 244 switch statements, averaging seven 
cases each. Fall-through occurred in only 3% of cases.) 

There is also a performance issue, in that the 
compiler must (because of the possibility of fall- 
through) evaluate each case in turn, up to the first 
match. But there’s an even bigger problem, 
architecturally: Switch statements require you to 
intermix code and static data. This leads to poor 
maintainability and a host of other ills. It would be 
better, obviously, to segregate code from static data so 
that when the data needs to be revised periodically, it 
can be edited without changing any code. 

The answer should be obvious by now: Convert 
switch blocks to associative arrays. Each case can be 
used, after all, as a key to find the associated action. (If 
the associated action is a block of code, then the array 
need only store a pointer to the appropriate function or 
macro.) In this way, you can collapse the entire switch 
block down to one line of code, which executes instantly. 

Consider the common situation, in CGI/forms 
programming, of retrieving a user selection from a 
drop-down menu and taking action on it. Usually, you 
have something like this: 

vat userSelection - 1 element .options Til, value; 
switch(userSelection) I 

case ’Kansas" : //JavaScript allows string cases 
do^tlils () ; 
break: 

case ’Ohio* : 

do^that(): 
break: 


// etc. 


default 


I 


whatever(); 
break; 


With an associative array, you can separate data from 
code and reduce all actions to a single expression. In 
JavaScript: 

// build .1 lookup table is an Object: 

var looktipTable * I 

‘KanfiafC : do_thls, 

* Oh i q * ; d o_t ha t • 

// etc. 

I 
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// execute action based mi lookup: 
lookupTabiei userSelect ion ]( ); 

An entire series of ifr'else statements (or a big, long 
switch statement) is thus collapsed to one expression, 
which does one lookup, then vectors to an action 
procedure. Code is segregated from data, making 
maintenance easier and less likely to introduce hugs* 
Performance is improved, many lines of code are reduced 
to one, and readability doesn’t suffer a bit. The best of all 
worlds, (fust don't tell your competition,) 

Sample App: IIasuMljle 

For this article, l wrote an educational utility for 
creating, studying, and comparing the collision raLes of 
hash functions. The app, called HashMule, is actually a 
PDF form incorporating about ISO lines of JavaScript* it is 
designed to run under Acrobat Reader version 4.0 or 4.05. 
You can download HashMule from http://- 
www.acroforms.com/archive/HashMule.pdf, or by FTP from the 
Mactech website. 

One of the things HashMule allows you Lo do is enter 
hash functions, then execute them against text in real time, 
A “Hash It* button on the form w ill hash every word of a 
given text block into a hash table, then report statistics such 
as table load factor and hash collision rate. By making small 
changes in the hash function and hitting the ‘’Hash It* 
button, you can see how the collision rare changes as you 
change “magic number" values or hash-function logic. The 
text of the Declaration of Independence is included in the 
form as a sample text block. 


For Further Information 

Associative arrays are such a staple of the Perl 
language (where they are called hashes) that you’ll find 
them discussed in detail in every decent Perl book and 
online reference. 

Few JavaScript references spend adequate time 
discussing that language’s built-in associative array 
capabilities. David Flanagan's JavaScript: The Definitive 
Guide (O’Reilly) is one book that does. 

An outstanding introduction to the Java 2 platform’s 
Collections Framework can be found at http ://- 
developer, java, sun, com/deve!oper/on I ineTram i ng/collections/- 
Collection.html. 

There are many good books on STL (the Standard 
Template Library for C++, which has a rich collections 
library). It’s difficult, however, to find good online 
information on STL maps. One worthwhile entry point for 
STL info in general, and information on <map> routines 
in particular, is http://www.dinkumware*com/htm_stl/index*html, 
Silicon Graphics, Inc* also maintains a very detailed 
online STL reference: see http://wwwsgLcom/Tedtndogy/- 
5TL/table_of_contents.html.Bui bear in mind that the SGI 
implementation of STL contains SGI-dcfined extensions as 
well as standard C++ templates* 

There are (IMHO) really no gcxxl books, ai this point, and 
precious few decent online tutorials, on hash techniques* For 
instructive online examples, you should search the Google 
search engine using keywords "hash" and “cryptography." 
(One paper that’s worth a careful look is http://wvmcs.cmu.edu/- 
~dst/CP4break/ f “The Breaking of CyberPatrol 4," by Eddy L O. 
Jansson and Matthew Skala*) Mi 


Fight Boredom 

Let's face it: Much of programming is boring 
and repetitive. Well, that's where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- View-Controller 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It's like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B»0»W»E»R*S 

Development 

P.O. Box 929. Grantham. NH 03753 • (603) 863-0945 • FAX 863-3857 
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Taking advantage of 
Apple’s standardized 
Type Selection API 


Introduction 

A feature frequently overlooked 
by new Mac OS users is ihe ability to 
select items from a list by typing pari 
of its name. Apple calls this 
functionality “type selection/* 
Seasoned Mac users are a ecu su aned 
to type selection and navigate rapidly 
through Finder hierarchies and 
Stand aid File dialogs without ever 
letting their hands leave the 
keyboard. When a user discovers this 
feature, it is probably with some 
disappointment that they find support 
for type selection varies widely 
amongst third-party applications. 
Every application that uses 
Standard File and Navigation Services 
dialogs gets type selection for free in 
those portions of their program. For 
custom application dialogs and views, 
developers have been required to 
write their own, custom type selection 
code* The result is that some 
applications don't support type 
selection at all, some support it to 
varying extents, and almost none 
support it in a way that mimics every 
last nuance of Apple’s own type 
selection algorithm. The op|xmunity 


to end these inconsistencies is before us, For Apple's Type 
Selection APIs have made their public debut. 

WiLhout fanfare, Apple included their Time -tested 
internal Type Selection APIs in the first public releases 
of the CarbonLib extension for Mac OS. As of this 
writing, the latest version is CarbonLib 1.0.4, and it is 
available from Apple's web site at 
http://asu.info.apple.com/swupdates.nsf/aitnuni/nl 16 
73- CarbonLib is the library that enables applications 
ported Lo Mac OS X\s Carbon APIs to continue running 
on Mac OS 9 and earlier (as early as 8/1) systems. 
There is no shortage of compelling reasons to port 
your application to Carbon. Apple's decision to 
support two platforms will] a nearly identical API set 
provides an irresistibly easy way of adding Mac OS X 
to the list of your supported platforms, without losing 
your existing customer base. Access to standardized 
type selection is by no means the greatest benefit of 
porting to Carbon, but it has the potential of causing a 
vast improvement in the user’s experience on the Mac. 

What’s Tin- Big Dial? 

You might be wondering why something as 
seemingly straightforward as selecting list items with 
the keyboard should require a standardized API. The 
user hits a key, you select a matching item, and we're 
done - right? Actually, the apparent simplicity of type 
selection is a testament to its internal complexity. You 
may not have even considered much of the 
functionality Apple's TypeSelect APIs provide unless 
you have spent a great deal of lime focusing only on 
the dynamics of type selection. Most developers do not 
have the time to become type selection experts, so they 
implement something that makes sense to them, yet 
lacks the subtle elegance of Apple's code. Some of the 
features of Apple's API are: 


Daniel Jalkut Is a software engineer m the Mac US X Carbon API group at Apple Computer. In his .spare 
lime. Daniel works on his guitar playing and book reading. You can contact him at jalkutitrecLsweater.com, 
or view his home page at www,red-.sweater,com. 
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// Like most Mac developers, 

// I easily spend 12 hours a day 

// staring at line after line of C+ + code in tiny, 9 point Monaco. 

// Sometimes it makes my eyes feel like they're on fire. 

{ 

So the last thing I need is some 
fuzzy monitor that adds to my headaches. 

} 



/***•*♦ begin excitement ****”/ 

H That’s why I’m so jazzed about this SGI monitor. 

// Its ultra-high resolution = 1600 x 1024 and dpi« no, 

// giving me razor-sharp contrast. 

// And the high refresh rate is 
// perfect for poring through lines of code. 

// At first, I was amazed at the clarity, the fine details that emerged. 

i 

It m <5 like teeing thing* for the firtt time. 

\ 

// Later, though, I learned to appreciate the wide aspect ratio |= 16:10]. 
// with a generous 17.3 inches of viewing area. SGI’s I 600 SW 
// lets me have all my documents viewable at once, and it’s 
// a flat panel so it fits on my desk with room to spare. 


// From the moment I saw this thing I was hooked. You will be. too. 

{ 

Especially when you find out 
how affordable it is. 

// Check it out. 


end excitement 1 




Michael Whittingham 
V.P.. Engineering 
Wired, Inc. 
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Support For international scripts, which Apple has 
always promoted, is becoming more and more 
important as the customer base for Apple outside of 
the United States continues to grow. As a developer, 
anything that provides international support for free is 
a big win for your product, because it is one fewer 
tiling you need to worry about when pushing to make 
a localized release available. Apple’s type selection 
APIs use script-aware string comparison functions, 
which in turn guarantee dial every selection made by 
the user causes a match as expected for the 
appropriate script. 

Multi-Character Matching 

A major shortcoming of some third-party 
ini pie mentations of type selection is that only the Iasi 
key pressed is ever used as a criterion for matching 
against items. If you type characters in a Finder view, 
you will notice that the active selection changes as the 
characters you type grow inLo a more specific match 
with the item yoifre seeking. For instance, if there are 
three icons in a view, “Belize”, “Bia-fra", and “Burundi*; 
typing just “B" will select the first, “Hi” the second, and 
dlu” the third. In an implementation that didn'i 
support multi-character matching, the user would be 
forced to type “IV to locate the first item, and then 
navigate with arrow keys to the desired item. No 
amount of typing would select either “Biafra,* or 
“Burundi” without moving a hand from the keyboard 
to the mouse. 

Time-Out and Cancellation 

One unexpectedly complicated aspect of a proper 
type selection implementation is elegantly guessing the 
train of thought a user has embarked on: knowing 
when to stop one selection and begin another. This 
task is impossible Lo do correctly every time, but Apple 
comes close with comfortable and consistent behavior 
that gives the user a great deal of control. 

The lype selection APIs keep a running tab of the 
keys that have been pressed, and when no keys have 
been pressed For a duration of time, that buffer is 
flushed, with the assumption that the user has finished 
typing the fragment they were seeking. To 
accommodate the user who knows they have 
mistyped, or who has quickly changed their mind, the 
APIs also respond to the escape key, which forces type 
selection to clear its buffers and begin matching keys 
as a new string. 

Implementing Type Selection In A List 

To demonstrate the use of the type selection APIs, 
1 have included with this article a sample application, 


“ListSampie", which simply displays a list of selectable 
items in a dialog. The applications responds to 
key Down events by passing them to the Type Selection 
API, TypgSeieetNewKey", which determines whether 
the key pressed justifies searc hing for a new match. If 
it does, another API, “TypeSeleetFindltem" is called, 
which uses the state of tile key buffer and a list of 
items provided by the client to determine the most 
appropriate selection. 

Application Prerequisites 

Before 1 could implement type selection in ListSampie, 
I first had to ensure that the application had been 
carbonized and compiled with Apple's latest Universal 
Headers. If yc>u have a I ready carbc >n ized yf >u r applit:atic>n, 
then you're ready to go. If you haven't, then you will need 
to do so before you can call any of the Type Selection APIs 
described in this article. 

ListSampie Implementation 

The easiest way to demonstrate the use of the lype 
Selection APIs is to explain the three pieces of code in 
ListSampie which interact with the APIs: 

• A TypcScleciRecord is initialized before any type selection 
can occur. 

• Key down events are passed to Type Selection, and a new 
match is found if appropriate. 

• A call hack routine for finding matches is implemented 

First, initialize a Type Select Record This is done by calling 
TypeSelectClearO with an empty TypeSdectRecord as its 
parameter. In ListSampie, this is done in inainO 

listing I: main 

Main 

Setup die menu bar. Initialize TypeSelectiuu. create our sample 
dialog Qnd ruts the event l«t>p until we are quit. 

mainC) 

I 

if Soup the menu bur 

SetffeniiRa t (Get. N’ewMRar (t AppMemiBarTD > ) ; 

DrawWenuBarO: 

// fnslialr/c the type selection record 

TypeSe I prtC 1 ea r (AfjTypeS** \ ectState): 

U Prepare the sample dialog 

gTheDialog = SettipSarnpIeDlalagi J : 

If (ftThtfDlnLog t= NULL) 

I 

// Handle Events! 

while (gQuitApplication = false) 

AppllcationEventLoopOi 
I 

DisponeDiftlofttftTherH aloft); 

I 

KxitToShelK); 
return 0; 
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Next, for each key Down event lhai periaias to the list, ask 
if a new' item needs to be matched, Tliis is done by calling 
TypeSdectNewKeyO - if it returns true, then it is time to find a 
new match for the list by calling TypeSelectFi n 1 1 Item. I have 
implemented this functionality in the [istSamplc routine that 
handles all key Down events: 


listing 2 : HandleKeyDownEvent 


1 Li ndk Kc yDownEve nt 

Handle key down events not handled by the Dialog Manager* If 
the key is not a menu-shortcut P than ask the TypeSelection 
APIs whether the key might change the state of the current 
selection, and if so* ask it to determine the new selection 

void HandleKeyDownEvent(EventRecord* theEvent) 

( 

Boolean eventHandled false: 

static IndexToSt ringUPP jnyStringGetter = HULL: 

//1 lamJle the and-key menu case first 

if (theEvent;-Modifiers b cmdKey} 

I 

long oemiKcyResult: 

menuKeyResult = MenuKey{theEvent->message &charCoeleHask): 
DoHenuSelaction(HiWord (menuKeyResult) * 

LoWordtmenuKeyResult)): 

1 

else if (gThdHalogUsi I- HULL) 

1 

// Only allocate the ImlcxTbStiingUPP once 

il (tuyStringGetter NULL) 

I 

// This call-back function b used by Type Selection in 
// fetch elements of the list the user is navigating. 
nyStringSetter * 

New 1 ndexToStringUPP(GetString£romlndex): 

I 

//Ask Type Select APIs whether we need to rcchcck 
// the selection 

if (TypeSelertNowKeyttheEvent, &gTypeSelectState)) 

abort 11atCount: 

abort newListlndex = 0: 

Cell nevSelection; 

// How many items are we dealing with? 

listCount - ( + *gTbeDIalogList).dataHounds*Lotto®; 

// Ask type Sdect for n new index, based 
// on the current stare of typing 

newLi at Index = Type So 1 ec t Mnd Item (GgType Select State, 
listCount, tsHormalSelect Mode. 
myStringGett.fi r P NULL); 

// Unset an) selected Items before t boosing 
// 2 new selection 

SctPt UnewS elec lion, 0, 0); 

// Starting at die beginning, get a selected cell 

while (LGetSeiect(true< dnewSelection* gTHoDialogLiat)) 

// Dnsckct it 

LSetSelecr(falsc, ncwSolection* gTheDialogList): 


// Set the new item to selected 

SetPtUrtevSelection, 0* newListltidex * I); 
LSetSelecrtyrue* nevSelent Ion. gTheDialoglist); 


//Auto scroll to make sure the selection is visible 

LAutoScroll(gTheDialogLiflt); 

//Workaround to list Box control behavior - LsetSdec! 

// causes an immediate redraw into the list s port. 

// which in the ListBox contml case is an offscreen 
// buffer allocated by the control manager, and doesn't 
// cause an update event to be generated for the parent 
// window, so wc need to Iwe a redraw. 
DrawOneDialogltemfgTheOialog, rDialogListBoxItem): 

) 

l 

} 

One of the parameters to the TypeSelectFindltem call is a 
callback mu Line ihai you provide to allow TypeS election to 
determine file elements of the list it is choosing from* 
Depending on the circumstances of your implementation* the 
items you are selecting from might not be a straightforward list. 
In our case the routine is quite simple* It simply J<x>ks up the 
desired index in the list control we are searching in: 

Listing 3: GetStringF rum Index 


CfCLStringFrom I ndex 

Callback routine for fhe type selection routine 
TypeEelectFindTiemO, This routine is called to fetch the 
Items in □ list, and detamines which of the items is the 
best choice considering the key strokes that have been 
pressed. 

pascal Boolean 

Get St ringFromlndex (short theTntiex. Script Code ‘whichScript. 

StrlngPu *whichString, void * ignored) 

I 

//pragma unused (ignored) 

Boolean returnValue; 

static 5 tr 255 thisString; // static because wc mum a 
// pointer to this string 

// Set the script - in this sample, wc know that 
// all the list items nrv in Roman script 

"whlchScript = smRoman; 

if (glheDialogList 1° NULL) 

I 

Cell desiredCell; 

short strlngLength * 255 ; 

// Fetch the item from the list, 

// and get the cell data (a string) into die result 

SetFt(idealredCeli, 0 . thelndex l): 

LGetCell (thisString F I, frstrl itgLengthp deal redCell P 
gTheDialogLlat): 
t h I sSuing [Oj = striugLeugth; 

*whichStriug = thi String; 
returnValue = true; 

} 

else 

I 

*vhichSlrIng - NULL; 
returnValue = false: 

I 

return returnValue: 

I 
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Summary 

Type selection is certainly not the top selling point of 
Carbon. The APIs I have described would have been 
appreciated if they were publicized years ago in the classic 
Mac OS arena, but at least they have finally arrived in 
Carbon. 1 hope this article has demonstrated that it’s not 
difficult at all to implement this functionality, and that the 
benefits to the customer are overwhelming. I hope to see all 
of your applications sporting fancy new type selection 
capabilities in their next releases Happy typing! 
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The tyjx* selection APIs consist of only four routines and one 
callback routine. Here is a short description of their functionality: 

lypeSelecrtlfcar 

Used to initialize a TypeSe lee [Record, which is the data 
structure that holds the state of type selection ar any given 
time. Call this routine at least once, when your application is 
starting up. After you launch, only call this routine if you 
want to intentionally void the typing the user has made at a 
given point, 

void TypeSelectCl&ar(TypeSelectR&cord *le e )i 

tsr Points tu aiypcSeleciRccoritl, which requires initialMUun. 

TypeSdcct Nov Key 

Every lime your application receives a keyDown event that 
might pertain to selection of a list item, you should pass the event to 
this routine. It examines the current buffer of characters and the value 
of the key event it is receiving, and returns true if die new keystroke 
has warranted the need Lu update the active list selection. 

Boolean TypeSelRrtNejwKey(const EventRecord 'theEvent, 

TyfHjSelectRecord *tsr): 

tlicEwm A pointer to an twii record containing a ktryDown event 
isr Wmvts to a TypvScdeoKtxXJ^ ptevimisiy iniii:ili/ttl wilhTypt y kvrClcsr, 

TypcStkaFmtlltcni 

When TypeSclcctNewKey returns true, use this routine 
to actually determine the most appropriate list item to 
receive the new selection.This routine takes as a parameter a 
callback function that you use to supply the algorithm with 
the contents of your list. 

short TypeSelectFindltera{const TypeSeJectRecord *tsr. 

short listSize, TSCodc seleetHode* 
IndexToStringUPP RetStringProc, 
void "yourDataFtr); 

l sir n lints to aTypeSdtxsJtecrad previoudy initialized wftiypcSdafttar. 

fctSrac ITh* number of items in iIk list you are; selecting from. If the number of items is 
unknown, pass OxTFH^surd Ik sure Uui uxir vaflbadc function returns foist- when a 
lapKMed index is not found 


select Mode Specify one of " isPrcvh JU^tectMi xk " I .Ofc jrnulStlectMudri , or 
XsNcxlSdecLMude’ to request the item before The matched item, the matched item itself; or 
Uie item alter tile matched item The piwkws and next modes arc. wku iIk Imfcr uses tu 
respond to the Tab and CmdTab knvTvpk.ilh you w ill [xass LsNumoJSdraMixk^ 

f^StringProc Riss a UPP to a routine llml will fetch string by mdes from the list of Rems 
you an' electing from 

youriy.kuPir Pass any value you would like to have passed back to your callback functioiL 


TypcSdecH a impart 1 


TypeSdectO>mparc is used to compare specific items from a 
list, using the exact same comparison that TypeSdeet would use in 
a call to TypeSelectFin elite nc This is useful if you have a sorted list, 
and want to optimize item selection based on knowledge about 
the sorting in the list. TypeSdcetHndltem compares each and 
every item in a list, so for very long lists pre-sorfing and using 
TypeSdcctCompare might result in a performance gain. 

short TypeSelectCoinpare(const TypeSoJoctRecord 1 tsr, 

ScriptCode testStringScript. 

StringPtr cesiStringPtr): 

lst rYrims to 7 T)pcSclcctRcctmi previous*) iiiiiiatizcd withTyptSdctlOear 
k>isirin0ktipi jinSeatcs iIk script cbc string dui b tiring compared. 
icstSu-jngPtr Rrintstn the string (hat is bring compared. 

My 1 ndcxTOStringProc 

This routine is defined by your code, and serves as an 
access point for TypeSclection to determine the items of the 
list that you are selecting from. When called, you will need to 
fetch and return a string from your list that is indexed by the 
given item number. You must return both a pointer to the 
string and the script code for that item. 

Boolean HyindexToStriDgProc(Short item. 

ScriptCode •itemsScript. 

StxingPtr *ite»sStringPir. 
void *yourOacaPtrl; 

item Tile index of the list item bring requested 

itentsScript You return the script of ihe requested siring litre. 

ttansStringPtr You mum a pointer u> die requested siring here. 

yourDaiaPtr A reference [*winter for whatever you choose. 
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MANAGING A 
WEBOBJECTS 
PROJECT 


By Darnel K. Every 


WebObjects Development Lifecycle 


What does WebObjects do? 


Article Scope 

There are many parts lo making a 
successful web-solution. The success or 
failure will be based on how good you (or 
your company) is at being an engineering 
company, engineering team or at least 
engineering project. If you aren't an entire 
engineering company then you are going 
to have to emulate all the facets of being 
one. If you don't have the size and 
experience, and are approaching rhe 
problem on your own or wiLh a small 
team, then you need to try to all wear 
many hats in order m make sure all the 
parts of the project run smoothly. Each 
part is important and will help you avoid 
pitfalls — so don't discount them. 

It is fjeyond the scope of this article to 
explain ail the concepts necessary to 
manage a successful team, how to do 
proper analysis, scoping, design, project 
management, as well as explaining how to 
lx j an interface designer, DBA and data 
architect. But it can sum up some of my 
experiences (many hard learned), and 
hopefully give the reader an introduction 
or review of the high level concepts on 
whaL to do, what not to do t and what are 
the warning signs to look out for 

This article is also tailored towards 
WebObjects project management — 
assuming an “average" project. Your 
project might not be average — but you 
can think about how you can borrow 
ideas and concepts, and how this 
information might help you.. 


Balance 

The key to creating a successful project is balance. 
Always remember the balances and tradeoffs. You have to 
balance your goals, with the customers desires. You have to 
balance marketing with engineering and with financing. You 
have to balance features (power) against simplicity 
(leafriability) — and form (style) against function (usability). 
You need to know your customers (marketing and feature), 
but you need to know what you can develop (engineering) 
— all balanced with what you can afford in time and money. 
There are many seemingly conflicting goals, and all of them 
have to weighed against the others and balanced. Everyone is 
not going to get exactly whai they warn — but If each gets to 
keep the important things, and they gel it in balance with (he 
others, then the product will probably be better than if there 
is no balances at all. 

Balancing the needs (and communicating them) is done 
in order to get everyone on the same page* and shooting for 
the same goal. Even if meetings seem useless or time wasting, 
they are valuable if you can build some consensus or let 
people feel like their views have been aired (and really 
listened to). Even if they don't get what they want, you arc 
more likely to get buy-in if they feel they have a voice and 
win some of the time. Even spending lime exploring paths 
you aren’t going to follow can be very important, if they can 
at least explain why the company isn't going to do something, 
or why things are being done the way they are. This makes 
your decisions more defensible and better understood. So 
meetings can be a tool to create consensus and understanding 
or they can decay into adversarial places where there is little 
real communication — always strive for the former. 

Conflict is going to be natural in the process — people 
are each advocating different views or different parts of a 
solution which are critical lo them. Accept that conflict, don't 
rake any of it personally, and don't hold grudges and try not 
to allow others to. You need to express a view strongly, and 
get over the fact Lhat others won't agree and you aren't going 
to get everything that you want — if you can t do that, rhen 


David K. Every is a Senior Software Engineer who has done many enterprise and client-server (n-tiered) solutions, a 
WebObjects programmer, and the creator of the MacKiDo website (http://www.MacKiDo.com). You can reach him at 
dke@tnackido.com. 
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you certainly shouldn't be involved in engineering. 
Remember that you all have the same goals -— to build the 
best product possible., in the least amount of time (with ihe 
lowest costs). Engineering is about tradeoffs and balancing 
all Lhe differing desires — but you are all shooting for the 
same prize. Keep reminding people of that, and keep 
reminding them that things will evolve and not gelling 
something now, may only mean for a while. Good ideas will 
keep coming back, and eventually win — and often things 
lose because it is just not yet the right lime for that goal, but 
not that their goal itself is bad. 

Unfortunately there Ls no magic to knowing where the 
lines should be drawn, when a project is unbalanced, and what 
to do about every situation. Nor Ls it easy to know where to cut 
off communications on certain paths, or all the nuances of 
managing people and delicate professional egos. That is all 
stuff that you just have to learn by experience, and there are 
books more targeted towards those subjects. However, if you 
at least remember to watch for balances, make sure that people 
are being heard and that your team is building consensus (and 
not hostility), people are learning why and where compromises 
are Ixhng made, and you are keeping communication open 
and constructive (with the eye on Lhe prize), then at least you 
have a head-start on creating a successful project. 

Managing the process 

There are many hooks on the theory of analysis, design, 
and development. Many explain how to decompose problems 
from different points of view, and different methodologies for 
GO A (Object'-Oriented Analysis) or OOf) (Object-Oriented 
Design) — and many more on the older procedural analysis 
and design processes. Some explain techniques for drawing 
how tilings relate, nomenclatures, methodologies, and mental 
exercise to break problems down, and so on. This article is 
noi one of those books. I've read many of those books, and 
Pm not knocking them — they have value and 1 recommend 
reading many of them, they have many nice insights that can 
help. However* most companies just don*t have a staff of 
people ail trained in the same methodology, at all levels of 
the company, in order to do a good job with them. Without a 
deep understanding of the processes (at the management as 
well as at the engineering level ) then the processes can 
quickly become less than efficient — and the results will 
probably riot meet expectations. 

The point of what analysis and design Ls really about 
should be as much about gelling people on the same page, 
getting them communicating well, managing expectations 
and getting some consensus and agreement on what will be 
done. It is setting targets that people understand and can 
shoot for, and measure progress against those targets so you 
can get better over lime. The processes, documentation and 
drawings, and exercises in many analysis books anti classes 
are not the ends — they are just ways to try to achieve the 
ends (common ica Horn, consensus, repeatability in 
forecasting, setting goals and managing expectations). 


Many of the larger, complex processes may be necessary 
and valuable on larger projects (say 15 engineers or more) 
with multiple teams, huge development cycles (over a year), 
and huge amounts of investment. However, successes in 
those processes are far more rare than the failures — 
especially if people aren't willing to be adaptive, or willing 
to accept the facts on scheduling or scope that is often 
staring them in the face. I’ve found that those processes are 
usually overkill for creating most web-applications. 

WebObjects is a powerful rapid application development 
tool that makes programmers much more efficient than many 
other tools. This magnification of programmers efficiency 
means that smaller teams can do more — and thus more 
projects are smaller with WebObjects than they would be 
without it. So the project management processes (including 
analysis and design) can be a little bit lighter as well. 

If you have a large team, of highly trained people, or a 
well established process that is working for you, then I’m 
certainly not suggesting that you throw it all away and try to 
mimic the suggestions of this article. Stick with what works. 
But there are many who are unsure about how to approach 
WebObjects development, or looking for alternative ways of 
thinking about that problem. This article is about techniques 
ihai I’ve learned and used in startups and larger companies 
to help establish a sensible process (or streamline one) for 
doing WebObjects development and project management. 
These are ideas for how to manage a WebObjects project 
(smaller, rapid development projects), while still maintaining 
a useful amount of documentation and process in order get 
things done right, and to si ill allow engineering enough 
critical communication to work well with other groups such 
as Quality Assurance, Documentation. Marketing, 
Management and so on. 

Go Visual 

If you verbally dcscrilte something to a group of people they 
will each imagine something different - they may think that they 
are all talking about the same thing, but in their minds they are 
picturing something that might be quite different from the rest. 
When one person delivers on whaL they were saying, the others 
often find that ii didn't meet with (heir expectations — and 
nothing seems to get people more frustrated then having 
something fail to meet their expectations (ask any married man). 
'Hie further away you are from their expectations, the worse 
things are likely to be - so one of the keys to successful project 
management, and a happy life. Ls good communications and 
n tariag i i ig expect a l k >n s. 

If you write a document that describes how something 
works, people are more likely to be on the same page than 
just speaking the same tiling. Speech is more imaginative 
than writing, and words on a page can be less ambiguous. 
Also people can digest written documents at their own 
speed, and review until they get it. So a well written set of 
design documents can really help facilitate communication. 
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Unfortunately, people are still victims of [heir ability to 
write, read and digest these documents — and those are 
skills that take time to master. Most design documents are not 
very good and tend to lake up lots of time to create, with 
little results, and tend not to survive confrontation with 
implementation — so by the time the product ships they are 
woefully out of date. Many people aren't willing to read long 
design documents — and just ignore them. So while design 
documents are usually better than just verbal concepts, 
written words usually aren't good enough to get people to 
understand what others mean. 

Most people tend to be visual and understand what they 
see, and they don’t have to conceptualize the intangible based 
on your description. Tims the key to successful documentation 
(or many discussion) is pictures and drawings. This is why 
many restaurant menus have pictures — don’t describe it, just 
show it, Don'i l>e afraid of a white board, a sketchpad, or a 
drawing program. It is cliche, but sometimes a picture really is 
worth a thousand words — anti people are more likely to use 
the picture than they are to read the thousand words. A few 
simple drawing, with notes and points can replace dozens of 
pages of wordy dexumentation. Because of this, I find to be 
the best form of design document, and tool for project 
management is the protoiyfxd 

Prototyping is the quickest way to get people to really 
envision the goals. And the quickest prototypes IVe ever 
used are just a series drawings, with a few notes to describe 
what each tiling does, and where items are labeled in go lo 
other drawings. At the first phase, I used Lo do this with a 
bunch of printed pages, and page numbers for each link, 
button or image, and just through the stack to show people 
where each was going. Later, 1 automate the navigation with 
some prototyping tool (like HyperCard or Visual Basic). With 
HTML and websites, ii is even easier to just link a bunch of 
static pages together and use that as a prototype that people 
can see and feel and sign-off on. 

With all this in mind, here is my simple process for 
analysis, design, documentation and project management. 

Analysis 

1) Analysts starts with information collection. Collect all the 
features and ideas that people want, and build a list (so 
many ideas won't be lost). And this is just the features and 
ideas people want for the first public release — keep a 
separate list for the far future stuff (that list will lie 
revisited after you’ve shipped TO). 

2) Prioritize the LO list, and divide it into three or four 
groups. Those groups will be iterations of releases. (I’m a 
big fan of iterative development — or at least a haler of 
waterfall development, since I’ve never seen the latter 
actually meet expectations, and ir always causes undue 
stress and frustration). The first few iterations are your 
targets for the first release — the last few are your visions 
for lire future or "nice to have’s*. 
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3) Most of the effort should lie focused on things that will 
make the cut. You can, and should, capture a few good 
ideas that can he in the other passes — but focus on 
getting people through the first iteration of the cycle. 
Remember to layer functionality — get the basics 
working, then add the “extras” later on. Let people make 
their mistakes early in the process when they are less 
costly — let them team what to do and what not to do 
before you are under the high-pressure end-game. The 
key to the early passes is to learn. 

4) Now go on to the next step and use the design process to 
mature your analysis — you don’t have to do all the 
analysis in the first stage of the first iteration of the 
process, let the next step mature the previous one. The 
goals are to get most done and revisit over time — not get 
everything done at once. Feature creep, design creep, and 
code-creep happens. Don’t fight it — just plan for it. Like 
a fine wine, let things mature on their own lime. 

The steps sound simple — but it can take quite some 
time just to get through that. In order to keep on track, try' to 
keep the analysis from getting into specifies and details — it 
is easier to just manage the higher level feature list, without 
letting people war over the details of implementation. Don't 
iry io do it all in the first pass. Make sure people realize that 
there are oilier iterations in the process — and that tilings 
will get in and that later planning will get into details. 

No analysis is perfect. In fact. I’ve rarely ever seen analysis 
that was realty close to the final product — and many of those 
that were, turned out to be exactly what was asked for, just not 
what people wanted. No one is omniscient, and since you can't 
anticipate everything up front, things are going to have to 
change. So you have to be adaptive, don't try to capture 
everything — just try to capture what you have at each step. 
Keep coming back, and keep things up to date — hut a series 
of small meetings and capturing what you have gives people a 
sense of accomplishment. Then come back and keep making 
those baby steps. If you try’ to do it all in one series of meetings, 
everyone will end up frustrated or bored, and you'll miss major 
chunks of functionality and lots of good ideas. If you keep 
revisiting over time, and capturing a few things on each pass, 
people get renewed and refreshed to add more each lime; 

Tip: 1 l is better if you don’t go into meetings empty 
handed. It will dramatically reduce the time to develop if 
someone is in charge of being the architect, or chief interface 
designer, leader, and they come into the meetings with a 
rough draft already sketched out. That person can capture 
half of the information via one on one meetings with the 
others before the bigger collective meetings — this is a big 
head start. When a meeting starts, it should be a continuation 
of where people left off — and just be about capturing any 
exira stuff that what was left out. Collaboration is useful but 
time consuming — so if you can get all the common stuff out 
of the way, then you are only left with the important part of 


There is a school of analysis that believes in using "use 
erases” to do the analysis. A use-case is a path through 
operation of a system (or the How of one feature). Usually 
one per role and function. Just follow a feature-flow to do 
one thing the user might want to do. Then add in others. 
When you document enough of the various paths (work 
flows), then you capture the behaviors necessary to 
complete the design. 

All this is pretty good theory’ — and use cases aren’t a 
bad way to do some of the analysis. However, I’ve yet to 
see a set of use-cases that were complete, or any analysis 
that was ever complete for that matter. If you try to do all 
the analysis up front — you'll come slamming Into a wall 
near the end of the cycle, as everyone stuns to figure out 
what was missed. Or else people spend far too much of the 
development cycle Lrying to figure everything out up front 
— when that knowledge would have been obvious (and 
cheap) if they had just been willing to wait for the omission 
to come to them. And you want to get everyone moving in 
ihe process in small steps (baby steps). 

Analysis without design and development time to help 
mature it, is like frying to create a reci[ie for great food 
without touching any ingredients, or an oven, it can lie 
done, in theory — but in practice, il never seems to work 
well. So start high level (very high level), then get an 
iteration done, then add more detail and functions and 
features in the next pass, and so on. Make a skeleton 
product (analysis, design, implementation, quality 
assurance, documentation), then repeal the process when 
you have a better idea of scope, time, and what everything 
is going to take, This will help you make your big mistakes 
early (when things are small) — so that you can recover 
easily and gel back on track. The longer you wait to 
complete every step of the process, the later in development 
you’ll lie when you discover the flaws — and the more 
time/energy and money it will take to correct things. 

Analysis, and use cases are valuable exercises that 
produce results and can easily save far more time than they 
cost — if you don’t abuse them. Use-cases in particular have 
always been a useful alternative way to help exercise the 
design and other analysis, and to give some groups like QA 
(Quality Assurance) a head start on building their test plans. 
But Fve found that use cases compliment the normal 
analysis, and aren’t really a replacement of it — just a more 
detailed way, or a different way of doing it. Glut 


collaboration (which is die areas that need to be discussed, 
and not all the stuff where people are in fierce agreement). 
This head start w ill get meetings completed in a fraction the 
time — and a good moderator (who keeps things on track, 
and schedules follow up issues for other meetings) will help 
get meetings over in a fraction the time as well. This makes 
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meetings more useful, productive and satisfying. 

Another important meeting rip is the duration. 1 hour 
mee Lings are about optimum (unless you can do them in less 
time). After a couple hours, people completely glaze over and 
start nodding to anything just to end the meetings. This is the 
FGADs factor Everyone jusi doesn't Give-A-Damn 31 when a 
meeting is running too long — they are just thinking of 
escape. The only thing worse than this, is the personalities that 
may become so pissed off (they're tired and frustrated), that 
the meetings turn hostile, and the meetings turn into a slug- 
fest, So it helps in analysis and design meetings (or all 
meetings tor that matter), to break them into many smaller 
meetings (one or two per day), than to try to rush it and cram 
it all in at once. Let the process happen. If people start getting 
tired and cranky or apathetic, it is time to break it up and 
come hack on a day when you'll be more productive. And 
sometimes if people are tired of one subject, it is better to just 
skip it, and address the subjects you can agree upon, and try 
to come back to "sensitive issues" later (another day or week). 

High Level Design 

Once you have a working set of high level requirements 
(which is what the analysis should have given you'll), use the 
design process to mature the requirements and create the 
lower level requirement. (High level design and low-level 
requirements arc almost the same thing). 

For a website, the high level design starts at the navigation, 
and then putting what function is at each point in the navigation, 
Thai is it 


Analysis vehsus Design 

It can be difficult to figure out w r here analysis ends 
(or should end) and where design begins. In larger 
organizations they try to divide up tasks so that they can 
throw more bodies at a process — but sometimes this is 
like 9 Women Irving to rush and have a baby in just one 
month, it doesn't work well. 

Analysts job are to do analysis. Because they 
specialize, they can add value to the process and offload 
the team. But there are also programmer-analysis who 
need to do to low-level analysis (and design). When 
analysis try to do the design, or you break up the analysis 
and design processes Loo much, then the analysis is 
abstracted from how the task will be implemented — and 
this usually costs in development time, it may allow more 
junior programmers to do Lhe implementation (assuming 
the analysis and design is perfect — which it never is and 
thus parts of the work have to be done over again, and 
again), or il frustrates senior engineers by treating them 
like more junior ones (and this can lead to conflict 
between engineers and analysts). So to do analysis and 
design effectively, you need to keep the analysts and the 
programmers (and designers) working together, not 
separate. Each has value to contribute to the process, as 
long as they are kept in balance. S5S 


Build a hierarchy (outline) of the site map, and how a user 
will navigate. 

On larger sites there may want to break the site into a few 
(or many) smaller sites. Each small siLe will be around a branch 
of functionality, or a role. 

Add in a list of functions for what each stop on the hierarchy 
should have on it (what features and functions are available). 

Other issues and ideas wilt be brought up that will need 
to be added to the requirements, or at least discussed as 
requirements. Don't try to solve them all at this level — 
maybe adding one or rwo of the obvious ones won’t slow 
you down, but collect a list of any of the more ambiguous 
ones, or ones that are going to cause contention to bring 
back to the analysis review meeting. This will keep the 
design meeting moving — solve the problems you can solve, 
and skip the ones you can't. And this will also allow the 
design to mature the analysis. 

At the end of this, you should have a site map — which 
is a nice visual way for you to see how people will navigate, 
and where they will get to various features and functions. 
This visual representation of where things go will help things 
mature much faster than it would have as just a spec. And 
you will be able to see that all the functions are captured and 
available somewhere. 
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Tip: I tend to use the weh to design the web — since I 
believe the purpose of die web is communications, this is 
“eating your own dog food", I make an intranet site for 
development that contains alt the notes/documentation from 
each step of the process. That site would contain (at this 
point) a simple high level requirements document, and a 
static site (navigation) map with each page being a iist of 
functions that page will do (and maybe what it needs to 
contain). You can do this on paper just the website is 
more interactive and publicly available, is easier to update, 
and saves trees. The designers and principals can now see 
what is where, and truly feel the hierarchy and the 
beginnings of a product. Everyone will start understanding 
the scope of the product and feel progress. 

Low Level Design 

Get an interface designer and graphic artist to create the 
first pass look, 1 call this the style-guide — what is the style 
and look of the site. This is just a simple picture for what 
each types of page will look like. Get a first pass of this done 
sooner because it gives people a lot of satisfaction to see 
some of the goals they are shooting for. Avoid needless 
battles over details, remember lo remind people that iliis is 
just a very rough first an (to gel started) — and the end 
result may not look anything like this. 

Decompose the common dements — both visually and 
functionally. 1 often do this with a User Interface Guidelines 
document that has a list of what rules that Em going to try follow. 
Know that this too will mature over time — so if starts small and 
loose, and will fill in as you go. Create a list of common features 
and functions that are repeated on many pages — and try to put 
these on all (or almost all) pages, and in standard places. This 
will allow reuse of code, and create an interface metaphor (set of 
common l>ehaviors that users will learn). 

Now revisit each slop on the site-map — and instead of 
having just the feature list on each page, create a simple 
sketch of where things will be. Since you have set of 111 rules 
for how things will behave, and a first pass at what things 
will look like, these sketches only really need to capture 
placement since you already have more details about look 
captured in the graphical style document, and the details of 
the feel is captured in the UJ document, I usually use 
rectangles with what is going to go where, though some 
people want more detail and like to actually put in place 
detailed picture from the HI guidelines and Graphical look to 
make a detailed mockup. 

Again, this phase of the process will mature the first two 
(analysis and high level design). The low level design will 
probably require changes and maturing of the high level 
design, and to a lesser extent modify the requirements. So 
capture any issues that are brought up, and quickly get past 
the ones you can't answer Do what you can. Let things 
happen in their own time. 

At the end of this, you not only have a site map, but you 
should be able to walk the pages with not only a list of what 


Top-Down ok Boitom-Up 

Some people design the back-end first, or do the data- 
analysis first (bottom-up design). ! tend to find that top-down 
(interface to model) is much betLer because it is less abstract 
and more visual 

Most non-engineers don’t understand FRDLs or data- 
dielionaries or da La-maps (the stuff you do at the bottom or 
from the data point of view). The non-geeks see these things 
and just just nod, and say, tt OK”, or “NO* without 
understanding what they are agreeing or disagreeing with. 
When you finally get around to implementing something, the 
higher-ups are less likely to say, “that's not what I thought 
you meant’ 1 when they've seen it visually (on screen shots 
and mockupsX Without an interface and that buy-in, it is 
impossible for a database to take into account all the 
requirements of the interface and application. So in bottom- 
up design, changes won t happen until you get to the top 
(interface) — and you want to get as many changes out of 
those the way as soon as possible so they have less impact, 
and so people understand what they are getting. 

Once you have the tangible and visible map of how the 
product will work (and look) people have much more faith 
in what you are doing — and you can show them exactly 
why you need a data element in the database or model, and 
what it is all used for. And you can lie sure that you are 
designing for the right target! 

Remember, you are building a Web Application The 
applications features and functions define what must be in the 
database — not the other way around. If you start with the 
database and data model (in design), what you are doing Is 
building a legacy database that you will then have to support 
with an application — instead of building an application that has 
a database supporting it! The top matures the bottom a lot better 
than the bottom matures the top. 

Nothing is black and white. Em sure there are a few 
cases where you have huge data requirements, and almost no 
front end or interface requirements — for those, 1 would do 
more a bottom up design, but if you are doing tliat, then you 
aren’t really building a web application — your doing a 
database with a weh front end. Heck, if you are doing tliat 
then you are building just a database with a thin presentation 
layer. WebObjects offers a “direct to well " junction (or direct 
to Java function), to enable you to just map the data Lo a 
simple user interface (if tliat is all that you really want to do). 
So by definition if you need to manage a project in 
WebObjects, you are probably doing a Web App and you 
should be thinking Application cenlrcc, which means top- 
down thinking (and not bottom up). 

For the most part, you actually do a little of both (top and 
bottom design) at the same time — and you actually start 
collecting the data from the interface as you go, and you can 
be working on the data set and data model in parallel. Just try 
not to lead with the database design. Sometimes there is no 
choice — and you must leant how to make an Application to 
work with a legacy database — but it never as easy as having 
a dean slate or going the other way, [go 
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is going to be on each page, but a little sketch of where 
things might be placed. You also have a rule book for how 
you’d like Things to behave. (Of course guidelines are not 
rules — just goals. They will have to change over time as 
well, and there will probably be exceptions — but the goal 
is to follow them as much as possible, and any deviations 
must have good reasons). Lastly you have a feel for what 
things will look like with the style guide. 

Tip: Again, 1 tend to use the web to design the web. I 
tend to pur the interface guidelines that are created, and the 
general look of the site on the developers intranet site. Since 
you already have a map how the site will navigate, with what 
features it will contain (place holders for each page), now 
you can just add what it will look like (roughly.) on each of 
those pages (in place). 1 put in the sketches for each page, on 
each page in the hierarchy (with some direct navigation 
links). This allows a simple working mockup, w-here people 
can navigate page to page, and see what each page might 
look like (very roughly) and what will be there. At the bottom 
of each page is a list of things this page should do, or at least 
a link to a page that has that information. And you need a 
section of the site to map what the common elements (that 
will be reused on many pages) will look like and need to do. 

Data Model and Back-End 

Now that you have collected the basic features and 
requirements for the interface, the database requirements 
should all be laid out for you. 

1) Collect all the data dements that will be needed from 
eac h of the screens. 

2) Pool the data in logical groupings what belongs with 
what. How do they relate to oilier items? 

3) Normalize the data so that common elements are in their 
own tables (and don't have to he entered more than 
once), and group data in a logical manner (often as close 
to mapping to the screens as is easily possible) and you 
should have a pretty good back end. 

There is a lot to doing a gcx»d data map that is beyond the 
scope of Lhis article — just like there is a lot to doing good 
graphic arts, or good III design that is also beyond the scope 
of this article. Hut at least these are the steps you can can take. 

This step in the process will help you find elements that 
you forgot for other pages (low level design), and can easily 
ripple up to the high level design and requirements. Go with 
it. After this stage you should have a system design that 
people can really shoot for. You have the top, and bottom. 
You have the basics of a look and a feel. You also have the 
behaviors of what each screen is going to have to do. You 
are now ready u> go. 

Tip: I tend to use the web to design the web — since I 
believe the purpose of the web is communications, this is 
"eating your own dog food". I make an intranet site for 


development that contains ail the noLes documentation from 
each step of the process. That site would contain (at this 
point) a simple high level requirements document, and a 
static site (navigation) map with each page being a list of 
functions that page will do (and maybe what it needs to 
contain). You can do this on paper — just the website is 
more interactive and publicly available, is easier to update, 
and saves trees. The designers and principals can now r see 
what is where, and truly feel the hierarchy and the 
beginnings of a product. Everyone will start understanding 
the scope of the product and feel progress, 

Middle Layers (Business Logic) 

The last thing you must do is start figuring out how to 
hook the back-end to die front end, and the design is done. 
On many small or mid-sized projects, it will go pretty quickly 
and there will be little need for a lot in-between (all the mid 
layers). On larger project, or complex project this can be 
quite an effort — but all this is traditional, and WebQbjccts 
doesn’t change how these processes are done. 

Often the list of features thaL are on the site map are the 
business rules. The what does this page have to do (from a 
business sense). Once you start trying to implement them, 
you find out that Those high level rules may take a lot of 
hack-end code. Many of these will be your middle layer If 
you embed them in either the front or back end (interface or 
database respectively), then you will usually make it harder 
to evolve and grow those over Lime. So often these rules and 
functions go in their own middle layer. 

The other thing that the “middle layer" is fur is a place 
to put commonality and things that you can reuse. Just about 
anything that is going to have to be used on more than one 
page, or on more than one entity, is a good candidate for the 
middle layer. This improves code reuse — which means 
writing less code, supporting less code, and of course few 
bugs (since repeated behaviors are implemented in only one 
place — so one fix, fixes all cases where that bug can 
manifest). 

if you just keep a watch out for things that can be 
reused, or things that don't really belong in the interface, nor 
in the entities themselves — then the middle layer wall 
mature itself, and all you should do is just keep a running 
list of what is in there, and where it is located. 

Project Management 

To do project management, you need to manage time, 
resources and scope. You can) do that effectively until you 
understand scope. Every step iri the process was just leading 
to this point. Now that we know scope, we have a starting 
point to calculate the other things — but first we have to 
project rough cost of the scope. 
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Time 



I found the easiest way to do project management is to 
just walk the site and documentation that I've bad to already 
create, and do time estimates on everything. There is a map 
of the entire site, with pages that explain what you need to 
do on each, and you've extracted all the common elements 
as well. What else do you need? Just put a rough time 
estimate on each “page" on how long it will take to 
complete, 1 usually measure this in days, with I day being 
the minimum, and with a week being a very complex page 
in WebObjects (that probably should have more of it's 
elements broken Into sub-components). Do the same for the 
global components and the interface scope is estimated. 

You still have to factor in the costs for the model - but 
that is usually a smaller scope than the front end, EOF is very 
fast at building the model, and then mapping the model to 
EC's (entity objects). So most of the programming load in 
this area is in common helper functions and business logic 
(the middle layer). But both the back end, and the front end 
design should give you a pretty good idea of what is 
required there. Just write down all the things you need to do, 
give them a rough load estimate, and add them all up. Those 
routines can vary far more in time to create depending on 
your business logic, so I don't know of any hard and fast 
rules — I just tend to approximate based on fractions of a 
clay, to days. But this will give you a working set of 
information on how far completed you are. 

Now don 1 ! forget to pad the estimates — not because you 
are lazy or because you are trying to add in nap-time, but just 
because of the inevitable scope creep. There are going to be 
missteps and additional things added. Also the further you get 
in the development process, the more the programmers are 
spending time supporting the features (and bugs) that they've 
already created, and the less time they have at just pounding 
in new features. So remember that the rate of development 
starts fast, and continually slows down through the process. 
This gets worse once you've actually shipped — because now 
you have customer support and those communication issues 
to deal with — and of course the more bodies you add to the 
process, the more communication overhead there is (and 
things get slower as well). 

The Iasi thing to do Is factor in all the final polish. 
Deployment is going to Lake time and resources. All the IS 
stuff, like setting up the machines, the servers, tweaking them, 
figuring out how to get everything talking, and so on, can be 
time consuming efforts. And then once you are ready to 
deploy there are other major efforts in profiling the App and 


Quality 

Experienced engineers and managers know that quality will 
he a function of all the legs of the triangle — but mostly time. 
The more time you have to mature the product, the better it will 
be. The fewer features you put in a product, the more time you 
have to mature the features that will make the product. And the 
fewer people you have on a project, the less communications 
problems (and overhead) and collisions you will have — but 
fewer people requires more Lime. 

Time over scope is the most important thing for quality. 
That is why l advocate iterative development. It allows you to 
get a small subset of the functionality in first, and get much 
of the early design done quicker (and getting you started 
faster) — thus buying you time (experience) for the rest of 
the project. 

Tire features implemented in die first pass, will have a 
few more passes to mature — and they are completed early. 
Everyone learns the processes early, when they are simpler 

— thus saving time (and not having Lo learn the hard way). 
People learn the product (or a key subset of it), as early as 
possible. Documentation gets a head start by being able to 
document Lhe I'irsL iteration of Lhe product (while die next 
iteration is being developed). QA (Quality Assurance), gets to 
be assuring the quality of the first iteration, while 
development is going on. Analysis and Design scales up in 
complexity only as it needs to — just-in-time for each pass, 
instead of having to do it all up front. You get to do test 
deployments of your solution earlier rather than later - thus 
you gel over those learning curves as soon as possible. 

This is all why three small steps are better than one big one 

— anil wliy you don't want to over design and over implement 
in die lirsi pass. You want to allow things to mature as they go 

— and give yourself more time (more stages) to go through every 

step of the process. By die time you release an iterative 
development prtxluct, it is really a 3 0 product, (assuming three 
iterations), instead of being a 1.0 version (with all the mistakes 
and issues being captured in one release, that you will have to 
fix in the next version).. HQ 


figuring out where lhe bottlenecks are (or are going Lo be). 

The total time estimate is just the count of all the time 
for all the functions. That should give you man days (or man 
months) of work — and you can use Lhai Lo estimate how 
many people the project will take for a given time. But 
remember, time is quality. The more time the project has, the 
belter Lhe results. A few people on a project is good — it 
gives you a diversity of ideas — but beyond a few. the rate 
of development does not increase much. And there are 
latency versus throughput issues. Some things just have to be 
completed before others can be done — it is critical to look 
for these things. Nine women can't have a baby in one 
month. You want to get starred on as many parts of the 
project as is possible as early as is possible. 


66 


WEB0BjECfs Development Lifecycle 


Mac Tech * October 2000 











It just tak' ts 
one bug... 

The sooner you find that last bug, 
the sooner you can ship, 
and the sooner you can sleep* 
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window and file logging services to Macintosh and can be used to record and display status and debugging information during 
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Tip: Again, ! tend to use the web to manage a web 
project. 1 put the time estimates on the web, often in an 
outline of the site itself — with total Lime and time 
towards completion (so far). Tracking how far you’ve 
come, and how far you have to go is pretty easy this way 

— and everyone can see progress and whal is left. 

Implementation 

Implementation is where the mbl>er meets the road. If is 
where you have to do what you said you were going Lo do. 
This is much easier now that everyone has agreed on what it 
is you said you were going to do. You have the basics of a 
site map, where each page will be, and what is going to be 
on each page. You have the basics of what you have to store, 
and where that should be in Lite database. And you should 
have collected the basics of the common dements. You even 
have rough estimates on how much time each thing should 
take, so you can divide up Lhe workload. Now get to work. 

If you were really thinking ahead, you could have given 
yourself a head start. A trick here is that 1 use WebObjects 
to create most of Lhe documentation and prototypes to get 
to this point, so that when it comes to implementation 1 have 
a working prototype and starter project. 

When 1 create a site-map for each page and function 

— I do it using WebObjects itself. Thus the prototype is 
the documentation, and the prototype becomes the 
implementation, just create a bunch of static HTML pages 
(using WebObjects), and use static links to take you from 
one page to the other. For the look, just include gif or 
.jpeg snapshots of what each page will look like — and 
at the bottom of each HTML page, I just put the list of 
things that this page needs to do. When if becomes time 
to implement, 1 just snapshot this project, and l have a 
starter project with empty pages all ready to be filled in. 
As I i m pIeinenl each page 1 have a list of th i ngs (ft*:itu res) 
that need to be done, and I just remove from that list as 
l go. The documentation of what still has to be done can 
be right there (in die programmers face). You can even 
add in notes and issues to each page, for all those little 
Lilings you don’t want to forget (the developer notes on 
limitations of a function or page). And if you are fancy, 
with very little effort, you put these in a conditional so 
that you (developers or internal people) can show these 
notes are not — and you can keep the documentation and 
issues always in sync with the product. 

The model work can be done the same way (on a 
smaller scale). I use EOModeter to collect a list of entities 
and attributes, and even show their relationships 
(sometimes). To create the documentation you can just 
generate the classes, and put in comments what each 
class or method needs lo do (assuming you are putting 
business logic in the model, and not above it). Using Java 
Doc can be a big help here. When I'm done with the 
design phase, I can jusi tell EOModeler to generate the 
SQL to create the database. 


As the design is maturing (as you go), you can even do 
other things. For global elements, create those elements 
(components) and what they need to do, and include them in 
or on the pages where they need to lie. Then global elements 
are global in die documentation as well as in the design (and 
you just need to replace them with the functionality and they 
will work everywhere). For a list of support classes and 
middle layer business objects and methods, 1 just create place 
holders and shells using FrojectBuilder. 

I was even thinking of getting fancy, and building a bug¬ 
tracking software right into the product itself (either the 
product or the shadow-product with the documentation) — 
so that QA could just turn on bugs using a back-door and add 
bugs right to the page that is having problems. And of course 
developers could view them and fix them right there as well. 
But there is a bit of work on that task (synchronization of 
pages and bugs, and gixxJ reporting abilities) — so I'm saving 
that one for a later effort. 

There is still a whole lot of work to be done to finish 
the implementation— but aL least these techniques can 
give you a have a head-start. 

Tlie goal is to make the documentation becomes the 
prototype which becomes the starting point for 
implementation. And later on the implementation can still 
contain parts of the documentation, and design notes, and 
other things. You can manage them in parallel, and keep the 
outline (with documentation, snapshots and project 
management, and bugs, etc) separate, or put them in your 
actual project There are strengths and weaknesses to both 
methods. On smaller projects I tend to keep them all in one. 
on larger ones, I've kept them in parallel — mostly because 
on larger projects l can afford to have someone else 
maintain the parallel effort, and it allows more diversification 
between versions. But the closer to the design you can keep 
the implementation (and vise versa), then the better you 
were at achieving your goals. Both ways result in getting a 
lot closer to your targets. 

IN-OUT, REPEAT IF NECESSARY... 

Remember, if you complete this process, you have 
only completed one iteration. That isnT finished, that is just 
the end of the beginning. So go back to the top, start over, 
and repeat ; "if necessary' 1 — and it is always necessary. 

WebObjects is a Rapid Application development tcx)L So 
don’t fight the uxA — use it. it is for prototyping (as well as 
deployment) t so use it for the prototypes. Websites are good 
for dynamic documentation. WebObjects is gtxxi for building 
websites — so use it if it makes sense for you. At least consider 
using HTML anti a website for your documentation — eat your 
own dog food. This all may seem blindingly obvious, but V m 
surprised by how many companies (and individuals) don't 
capture their goals in simple design documents, or how many 
don’t use prototyping or online documentation. 

Analysis and design don’t have to be hard. Most of the 
academic books written on these subjects have good ideas 
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in them , and good techniques — but can't be followed to 
the letter in the real world Most of them are such overkill 
(for the commercial world) and so complex that people 
either waste too much time trying to do everything, they 
get frustrated by the books and all the things they have to 
know so they do nothing, or most often they try to do the 
former (and do everything) and burn out half way through 
and give up or say, “good enough" (and end up with 
nothing). Be pragmatic and use what works — for me, it 
has been starting at the top, and making a thin shell, and 
then filling it in and maturing it over lime. In Aerospace, 
BioMed, or some financial institutions, there is so much 
risk to what programmers are doing, that they can afford 
huge lime wasting processes and reduced development 
efficiency (and larger head-counts) for the sake of liability 
and documentation. Most commercial organizations can 
not afford that. Know your market, and what makes sense 
for your company and market. 

Most companies try- to separate develop men! from project 
management, and apply abstract project management tools and 
layouts to a development task. Ii doesn't have to be that haul 
just collect the requirements (scope), and layout how much time 
each thing will take, anti add it up. You'll miss, but you'll usually 
be much doser than if you are basing your estimates on more 
abstract technique*. The dtxser you are to development (in the 
time estimation process) tile doser you are likely to Ixe to the 
target, and tile better your estimations are likely to be 

It Ls amazing how many projects (and managers) still try to 
still do waterfall processes. They try to do all Lhe design up front 

— as if we are* omniscient beings — and they ignore how back- 
loaded the process Ls. You slow down as you go, because as you 
go you need to keep adding in more and more tilings — like 
documentation, support, bug fixing (and bug hunting), and so 
on. You also need to adapt to change as you go, and accept that 
feature creep Ls going to liappen. Don’t blame — try to capture 
the change request for a future version or reprioriiize and trade¬ 
off functions — but accept change and that you can't think of 
everything before you start. 

it takes many tries to get things right. Instead of trying 
to do it all right the first time, just accept the iterations and 
pick the low-hanging fruit. Layer the development (and 
analysis, and design) into iterations. This makes things 
simpler early on — and so you make quick progress (rhus 
making everyone feel happy and productive). This also 
teaches everyone good habits (the process). The problems 
you think you're going to have may not materialize, the 
ones you are likely to have you weren't going to think of 
anyway. Don't design for features that may come down 
the pipe in years (or that you’ll never have lime to get to) 

— redesign when you need them, you’ll know more at 
Lhai time, and you’ll have learned more during the time in 
between f so are likely to make better decisions later 
anyway. So by starting simple, you are training people on 
something easy, so that in later iterations, as things get 


more complex, everyone is trained and comfortable on the 
process. When later (tougher) problems come up, 
everyone is more skilled with the process, as well as 
understanding the solution — so they are more ready to 
respond to any problems that arise. 

Lastly, by doing iterations, you always have the safety 
net of previous iteration to fall back on (if you are late to 
delivery). You not only have a more accurate way of 
mesauring how far you’ve come, how much Ls left to do, 
and how long each iteration takes — but you will have 
addressed the most important functions first, so they have 
the most rime to mature. And while earlier versions may 
not he as full functional as the goals, they will be working 
versions which you can ship if need be — thus reducing 
risk to the company. 

Doing things in layers (iterations) is faster, easier, 
makes everyone see progress and gel more motivated. 
You are able to show others (investors or customers) the 
product sooner, and even sell it sooner. And it gives you 
more time to develop and mature the product - thus 
meaning a better product, for less time and less effort. 
Which is what the whole development process is about. 
Fortunately, WebObjeets as a loot, can help make many 
steps of the process easier as well, if you use the tool for 
what it is good for. QQ 
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MAC OS X 


By Andrew C. Stone 


An Intro to Mac OS X’s 
Command Line Interface 


Back in the mid to late eighties, 
DOS was king and PC users would 
make fun of the “MacInToy* simply 
because it had no expert command 
line interface (CD). Of course, this 
was before the PC world ditched 
their own command line interface in 
favor of an uglicd down graphical 
user interface that poorly copied the 
Macintosh’s finely detailed GUI. 
Being an old Unix weenie from tile 
academic Computer Science scene, I 
can understand the argument that 
the command line is an extremely 
powerful tool for expert users and 
programmers. Of course I also 
understand that it needs to be 
hidden from the casual user, lest 
they type •‘rill -I'f /" as root and 
totally erase their hard disk! 

And now, the CL1 is just one 
more compelling feature of Mac OS 
X< OS X is based on Darwin, Apple's 
version of the open source FreeBSD 
3.x combined with the Carnegie 
Melon University Mach 3-x kernel, 
The command line and all the 
standard l'nix utilities are part and 
parcel of the developer distribution. 
While it is still not clear what will or 
won't ship to the end user in the final 
OS X, DP4 gives you Terminahapp 
(/System/Admin Lslration/Terminal.a p 
p) to provide a "shell ' allowing you 
to type commands directly to the 
computer for both interactive and 
batch processing. This article is an 


introduction into the use of the command line, and l 
hope to provide enough information to convince 
unrcpentent GUI freaks that a CU is indeed useful, and 
share some cool n icks, tips and information on where to 
go to learn more. 


She Sells C-siiells 

Once upon a time, there was just the c-shell, 
/bin/esh. However, Unix hackers love to cram more and 
more features into any one given program, so now there 
are several shell programs to pick from, including; resh, 
esh, zsh and bash. When you double-click Terminahapp 
to launch a shell, Terminal uses your default shell as the 
command line interface. In a standard installation, the 
default shell is icsli. Your default shell is stored in 
Net Info, and can be set by editing the User in 
/System/Adminis!ration/NetwcjrkManageraipp. Click on 
"Users", then select a user, then edit the shell field to the 
complete path of your desired default shell. You can 
always switch shells on the fly by just typing the name 
of new shell. Each shell has its strengths and supporters 
- you might play around to see which one you prefer. I 
use bash whenever 1 need lo be able to include newlines 
(returns) in a command - and it handles filenames with 
embedded spaces rather well. Bach of the various shells 
share a lot in common, but syntax does vaiy from shell 
to shell, so I'll just use the most basic examples here 
which at least apply to esh, In any regard, launch 
Terminal.app so you can start to play! 

Man - the manual pages 

One of the l Jnix shell s most useful features is the built in 
manual pages, which document all the commands. Before 
we leant alxnit "man", a short discussion of why Unix uses 
such cryptic and abbreviated names is in order! If you have 
some familiarity with DOS, you'll know that to copy a file, 
you tyjx. 1 : 

copy <FTLE_1> <FILE_2> 


Andrew Stone <andrcw^.stone.com> is founder of Stone Design Corp <http://www.jatDne.c om/> anti has spent 12 years 
writing Gx:oa software in its various incarnations. 
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Making the Move 


The same command in Unix is “cp". It seems early 
Unix programmers haled to type and loved lacunae - 
and you'll learn Unix shell programming faster if you 
can uncover the mnemonic embedded in each 
command. For example, esh = C shell; mv = move* In 
= link; Is = list; iiikdir = make directory; etc. But the 
cool thing is that you don’t have to remember much to 
use Unix because the man pages detail the use of 
every Unix command. For example, to learn about the 
manual pages, type: 

man man 

You'll see something like: 

MANfl) System Reference Manual KAN(1J 
NAME 

man - display the on line manual pages 
SYNOPSIS 

man pachw] |-C file] [M path] [ m parti] Unction] name ... 
DESCRIPTION 

The man utility displays the BSD Unix manual pagpfi 

entitled name. 

The options .irc as follow s: 

a Display all of the manual pages for a 

specified section and name combination. 

(Normally, only the first manual page found Is displayed.) 


With HEEDS ■ just over the 1 > [t| il MlUL 
Mac ieyelopCf S everywhere have a 
major need for CARBON and 
application porting, . user interface 


When you can’t remember the command that you 
want to learn about, you can always try the apropos 
command, which searches the man pages’ names for 
the given word. For example, typing 


implementation, and IHRillii development 
services. Toward that end, several 


apropos directory 


gives back a list of Unix commands whose 
description includes “directory* (directory is the Unix 
term for folder). 


basename(1), dirname(l) 


cdUJ 
cd (n) 
ch<lir{2). 
chroot(2) 
chroot(8) 
dir(5)* dirent(5) 


fchd i r (?.) 


Dir Handle Cl) - supply object methods for directory handles! 
EindBinO) Locate directory of original perl script 

TciJCratmlaleFilcNamefl) - convert file name to native form 

and replace tilde with home 
directory 

return filename or directory 
portion <jT pathname 
change working directory 
Change working directory 
- change current working directory 
change root directory 
change root directory 
directory file format 
directory(3), opendir{3)„ readdit(33* Telldir(3), seekdir(3), 
revtnddir(3), elosedlrO). dirfdU) directory operations 
ditto(8) - copy source directories to destination 

directory 

getcwcl(3) r get pathname of current working directory 

getcwdOU geiwd(3) - get working directory pathname 
getdirentriesU) geL directory entries in a filesystem 
independent format 

- list directory contents 

- make a directory file 

- map a directory hierarchy 
find a directory in the NetInfo hierarchy 

- read and write Hie archives and copy 
directory hierarchies 


U(l) 
mkdir(2) 
mtree(8) 
nifirtd(l) 
pax(l) 


high-quality engineering 

firms, in association with the 0PPLI 
DEVElOfTB CONNECTION, are offering these 
services at very aJif'acilve discounts 
to all ADC Select and Premier members. 


The following pages 
are those vendors that 


October 2000 * MacTech 


are part of the Mac OS X 
Porting & Development Showcase. 











ShadeTree 




Software Development 
Outsourcing Since 1990 


415.491.220( 

www.shadetreeinc.corr 









3et the power and experience you need from 


PROSOFT 
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With over thirteen years in providing 
programming service to the Mac community. 
Prosoft is committed in delivering the ultimate 
quality software products and service. 


Our Engineers have extensive knowledge in: 


• Macintosh PPC Drivers, 
Shims and Extensions 

• Macintosh Power Plant 
Applications, Mac OS X 
applications and drivers 

• Carbon application 
porting for Mac OS X 

• Multimedia and QuickTime 
Applications 

• Unix/Linux Console 
Applications, including 
Unix Solaris, xBSD Drivers, 
and Linux Drivers 


0 

• Windows 95, 98 

ft 

• Window CE 



0 

• Windows NT, 2000 

ft 


0 

Ul 

• Unix / Linux 

0 



• Java 

ft 


X 

"O 

• Embedded OS 

ft 


(A 

ft 

• RDBMS 

• Network Consulting 
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Eat your vegetables. 
Exercise every day. 
V Port to Mac OS X. 

T Call your mom. 


All of these are good for you. 

! We can make one of them easy. 

Since 1980, The Omni Group has worked with the technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

Thai's been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

• Real games: We ported id's Doom and Quake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's FrameMaker to NEXTSTEP and Sun's Concurrence to OpenStep/Solaris. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

• Serious drivers: We ported 3dfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmniWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


Ti 


Omni 


Group 



2707 Northeast Blakeley Street 
Seattle, Washington 98105-3118 
wvrtv.omnigroup.com/cnnsulting 


sales@omnlgroup.com 
800.315.OMNI x201 
206.523.4152x201 
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“We have found the engi- 
neers at Art & Logic to be 
outstanding—better than 
excellent. When we use 
their software development 
services, we get results.” 


Art & Logic, Inc. 

www.artlogic.com 
877-278-5644 (toll free) 
info@artlogic.com 


The software engineering company that helps bring your 
hardware product to market—guaranteed. 


Since 1991, high tech companies like Apple Computer, 
Hewlett Packard, and Leica Microscopy have turned to 
Art & Logic for assistance in implementing cutting 
edge technologies. 


Now, with the advent of OS X, Art & Logic is helping 
companies make their products compatible with 
Apple’s new operating system. Art & Logic engineers 
are industry leaders in Carbon & Cocoa porting, Aqua 
implementation, and driver development. 


In the new economy, where time to market is every' 
thing, you need results. Art & Logic delivers. 
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With the experienced 
Mac OS development team. 


Red Rock Software specializes in the Macintosh software devel¬ 
opment. Red Rock Software's team of senior engineers aver¬ 
ages over 10 years of development experience on the 
Macintosh platform. Our expertise and experience has gained 
us the trust of companies like Apple Computer, Iomega 
Corporation and Sorenson Media. 

If you are looking to get your product compatible with Mac 
OS X quickly and with extreme quality, let our experts help. 

• Aqua Interface Implementation 

• OS X Carbon Porting 

• OS X Native Cocoa Application Development 
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software 

call Red Rock at 888.689.3038 
or visit us online at www.redrocksw.c 
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development, Windows to Mac porting, Carbon porting 
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projects on time. Our clients include a veritable 
who's who in the industry - Apple, Adobe, 
Quark, FileWave, Versaware, Veon, NetJumper, 
CEI, The Anderson Group and eCapital, among 
others. To know us better, visit our website 
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pwd(1} return working directory name 

pwd(n} Return the current working directory 

remove(3) - remove directory entry 

n*{I) remove directory entries 

nadirU) - remove a directory file 
scandir(3), alphasort(3) - scan a directory 
unlink{2) - remove directory entry 
whols(l) internet user name directory service 

Apropos reveals the rich set of commands 
available to both the command line user and C 
programmer . The number following the command 
indicates which man subdirectory should be consulted. 
To read about a man page in a particular subsection, 
for example, scandir(3\ you'd type: 

man 3 scandir 

If you just typed that in, you 11 notice that it's 
actually a C language prototype, and not really 
available as a command line call! If the subdirectory is 
1, it’s a shell command; otherwise it's a C function. 
Still, most standard C library functions are exposed as 
callable binary programs or slid! scripts. 

Anatomy of a Shell Command 

After looking at a few Unix man pages, youII 
notice that a consistent style is used to make it easy to 
grasp the functionality and options of a command 
Hie simplest example is a command which takes no 
flags or arguments, for example: 

dale 

A flag modifies how the command works and is 
represented by a letter or digit which follows a 
(clash) or another flag. Arguments are input to the 
command, such as filenames or folders: 

Cp rf /bin/cat /tup/catty 

command flags argument 1 argument 2 

The man page presents a synopsis of the command 
in a standardized notation to express when a flag or 
argument is optional and/or repeatable. Let’s look at 
the first example of the synopsis of “man" to learn how 
to decode rhe notation: 

man [achw] [ C file] [ M path] I in path] [section] name ... 

Anything enclosed within T* and “]" represents 
optional flags and arguments. For example you could 
include -a or -c or -ac or -ca or -achw as valid flags to 
rhe man command. 

When a word follows a flag, you must provide an 
argument if you use that flag. For example [-M path] 
means that if you use the optional -M flag, you must 
follow it with a full path name. 


If you see ellipses, such as at the end of the 
synopsis, ii means you can provide any number of 
additional names as arguments to the command. 

All of the flags and arguments are described in the 
body of the man page for the command. Also, at the 
end of the man page is a section which gives 
additional related commands. For instance, on man's 
man page, you would find: 

SEE ALSO 

apropos!1), whatis{l). whereisUK nan. conf (5). oidoc(7), 
mtfoc.samples(7) 

Do a ‘‘man" on soma of these to keep learning more. 

Less Typing, Moke Power 

Power users, who are always looking for ways to 
maximize the amount accomplished with a minimal 
amount of typing, use initialization files to 
personalize their shells, Initialization files contain 
environmental variables, aliases, and other 
customisation**, such as a clever shell prompt. Each 
shell program looks for a different initialization file; for 
example, esh uses -/.eshre and bash uses -/.bashre. 
Extra Credit: using man, Find the name of the 
initialization file for tsch! 

Aliases :ire short cuts to make complex commands 
that you use available with just a few typed c haracters. 
For example, let's say you always want to see your 
directory files listed in reverse order of the time 
created, that is, with the newest files listed at the top 
with Lite long listing: 

U it 

You could add this line to your -V.cshrc filer 
alias It “Is -lt w 

Next lime you .start a c shell (or type the command 
“source ~/.cshrc” to reread the initialization file), when 
you type "It”, you’ll get the equivalent of typing “Is -lt'\ 
People love to put gnarly prompt creation commands 
in their init files, and this example is about as scary as 
they get: 

alias cd \P: set currDir = ' basenaine Scwd’: set currEir = 
'echo “<$lhostl:*$currDir 
“ I >"' : set prompt = “$1 currDir! **' 
c .d $cwd 

This produces a lovely, palatable prompt which 
tells you which machine you are on, which directory 
you are in, and the number of die current command, 
for example: 

<hermionea Developer 24 > 
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Which leads us lo a disc ussion of typing less t hrough 
use of history and command substitution. Your “history” 
is a record of the commands you’ve issued, Type 

history 

to see a numbered list of the commands you have typed 
recently: 

] cd 

2 cd Library/Preferences/ 

3 rm ApplicationCacheTheFinaiChapter 

4 ps axw | grep Kail 

5 man man 

6 apropos link 

7 apropos time 

8 apropos link 

9 apropos directory 

To repeat a previous command, for example, “man man”, simply 
type: 

n 

!5 is pronounced “BANG-5" in Unix. A ** n is “splat 11 . A "I* is a 
pipe, although French Surrealist painter Ren> Magritte would say, 
“Ce riest pas un pipe”! 

To repeat the last command issued, type: 

it 

To refer to the last argument of the last command, use ,P !$". For 
example: 

cat t$ 

displays the contents of the last file you referenced 
in your last command. 

In some shells, you can use your up and down 
arrow keys to repeat commands issued before. 

Because many shell commands operate on files, 
and because typing file names is tedious and prone to 
error, you have various shortcut options. 

Most shells have builtin “escape completion” which 
will complete the names of files and folders if you type 
the first few unique characters and then type your 
escape completion key (this might be “ESC” or F5 or 
even TAB in some shells). The vanilla C shell has this 
turned off by default, but you can add the following 
line to your .eshre file to enable escape completion: 

set filer. 

As of DP4, tiie default shell is isch, which has 
escape completion on. Type two escapes if one escape 
doesn't complete anything. 

And, for you GUI junkies, OS X lets you drag and 
drop files or folders from the Finder onto shells, 
instead of laboriously typing out entire path names. 
You'll even geL the correct escape codes for spaces, or 


October 2000 * MagTech 


www.macshowlive.com 

Everything* Mac 
Every Week 
Live! 

Each Wednesday Night 
join us for: 

* Mac News Review 

* Featured Live Guests 

* Regular segments on: 

• Gaming 

* Basics 

■ Tech Tips 

And audience 

interactivity! 

- java and IRC Chat 

- Toll-Free Phone-in 

- Contests and prizes 

To listen, you'll need: 
QuickTime 4, a Modem and a 

Mac 


'almost 



Every Wednesday 9-1)PH EST or listen to a stream or 
download archive of the show anytime! 

www.macshowlive.com 


















perhaps the whole path will be correctly quoted. 
Because the shell interprets “words” (alpbanumberic 
strings separated by spaces or tabs), you need to use 
io either “escape 1 * the characters with a backslash: 

cd /MacV 0S\ X 

or type ii with quotes: 

cd "/Mae OS V 

Bulk Processing and Iterations 

Where a CL1 has it all over a GUI is when you need 
to perform some boring, repetitve task on a bunch of 
files. For example, suppose you want to change the 
path extension of a whole folder full of files, say from 
VriF' s to “.tiff' You can't do this in a GUT without an 
additional program, buL in Lhc C shell, you can use a 
simple looping shell command, using the “foreaeh” 
statement. Type: 

foreach i ( *.TIE ) 

At this point, you enter an interactive subshell with 
a new prompt, “ ? T You can type any number of 
commands for sequential processing, referring to the 
current file as $i, and the “root" of that file ($i:r), ie, 
the filename's full path removing ir‘,s path extension. 
Sec “man cshrc n for more info on referring to parts of 
a file path. Finally, when you are finished issuing 
commands, type end and computation begins. 

7 echo $i // which file :ue we on? Well prim it out 

7 mv $1 3 i: r , tif f // move Lhai file to tin: name, less extension, plus tilT 

? enrf // This terminates the loop and begins processing 


Plumbing: Input, Output and Pipes 

Unix is designed for hooking up ihe ouiput from 
one process to the input of another. This is done 
through two basic mechanisms: redirection of standard 
in pul/stan dart I output and pipes* 

The less than symbol, means take input from 
whatever is producing output on the right hand side of 
the “<*\ For example, you can use the command line 
“mail" to send ascii files: 

m\l harry@Gtone.com < /ere/hostconf \g 

You can use I/O redirection whenever a command 
expects standard input (stdin) or produces standard 
output (stdout)* When a process expects a feed of 
input, ihen you must rely on the chaining of processes 
through pipes. Pipes can be used effectively with 
gnutar ro copy large trees of files to new locations: 

(/usr/bin/gnutair chf - Stone_CD) | ted /Backup: 

/usr/bin/gnutar xf -) 


Note how you can also stage commands by 
separating them with a V* Here, we are creating a new 
“tar’ 1 archive, changing to a new directory, and then 
unarchiving it to standard out, thus copying the 
original hierarchy of files to this new location. 

Once you get the hang of Unix, you'll find that you 
can do all sons of tasks. For example, the age old bean 
counting task of counting lines of code can be done 
trivially using the powerful and confusing “find" piped 
u> the meta-command "xargs” which calls the word 
count program “we”. Assuming you have changed 
directory to the top level of your source code, type: 

find . -name ’ 1 .[bmcl’ | xargs we 1 

which translates to: beginning at the top level in 
this current directory, recursively find all files which 
end in either .h, .c or ,m, and use each file found as 
the input to the word counting program, with the 
option of counting only lines (not words or 
characters), with the bonus of providing a grand total 
of lines. What may look like jibberish will soon 
become recognizable and habitual! 

And, for authors paid by the word and to honor 
the oft times obfuscated nature of Unix, here's an alias 
for your initialization file: 

alias uordcount 

(cat I* [ tr -s * *,;:?!() II " T '\01Z l | cat -n | tail 

1 | awk *1 print sir) 

and you would use it in a source directory by typing; 

wordcount *. [hntc] 

To go “deeper* you jusi add on more arguments: 

wordrmmt - * [hmr 1 */*/*[hinc] 

Conclusion 

It takes years to learn Unix completely, but only 
moments to learn enough to be useful. The online man 
pages allow a quick refresher course in any command 
and are an excellent lifetime reaching tool. The shell is a 
power user s friend and can expand Lite capabilities and 
productivity of OS X. Granted that it is not for everyone, 
but for those who dare, it's a true bonus! HQ 


Want to share a tip with the 
community and get paid for it? 
Send it in to 

tips@mactech.com 
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The new way to sell software 


Mind Vision Software, creator of Installer VISE, introduces eSellerote, the quick and easy way to 
speed up your online sales. Designed especially for developers like you, eSellerote puts instant 
gratification into the hands of your customers. Now, your application can sell itself with no 
manual intervention from you. None, nothing. Noda. 







TOOLS OF 
THE TRADE 


By Tom Djajadiningrat 


Satimage’s Smile 


AppleScript IDE 


Introduction 

Smile is an AppleScript integrated 
development environment which is highly 
scriptable itself. It offers u tine text editor, 
pretty good documentation and the 
possibility to look up definitions from 
within the editor But Smile's most 
amazing features are its ability' to execute 
a script line-by-line from a seemingly 
ordinary text window and that its interface 
can be customized at will. 

Since it is essentially free — all 
Satimage asks is your feedback to further 
improve Smile — it makes a great 
replacement for the standard Apple Script 
Editor. After a while you realize that Smile 
is much more than that. It brings together 
in a single application a combination of 
features which force you to rethink the 
possibilities of AppleScript, 

ReDUIREMFNTS 

* Smile (downloadable from 
http://www.tandb.com.aii/smile/ and 
http://wwwusers.imagtnet.fr/-satimage/,) 

* A PowerMacintosh (Smile does not run 
on 68K machines.) 

■ 

MacOS 8.5 (unless you are willing to 
mess about with the Navigation 
Services and Appearance extensions on 
earlier systems.) 


A Superior Editor 

Despite its name, the editing features of Apple’s Script 
Editor have always been somewhat poor. Especially its lack 
of drag-and drop and scardwind-replace is rather annoying. 
Smile is worth getting just for these features. In addition, 
Smile features live scrolling, can compare files, has no 32k 
size limit, and implements Appearance. Command clicking 
the title bar of a window gives CtxleWarrior-like access to its 
file's path (Figure 1). This in combination with support for 
Navigation Services makes organizing files much easier. 


d ■ a'.wmi'M— ?'f ?0B 
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To get started, double-diet thtj 
The comprehensive guide is ova 

Hev 1,7.2: A ww 'VarteWe vtfctur 
hexe string (Mxivtrsloft, ft*v f&ut- 
documentation <ia now pri ntable as a v 

Qt Smile f 

Cl SmMet.7,2US 

Cfi Programming 
Q Apps 

a nW sen peso ie 
Inss te handle AppfeSerip 
Itwli. 

nu. 

Messages' vindov, a much, faster 
i s text item delimiters, the 



Figure L Smile provides easy access to a file's path. 


If you are a keyboard animal then you will appreciate that 
keyboard navigation and selection are fully implemented Jump 
word (option + left/right arrow key), jump start end of line 
(command + IdVright arrow key), page up/dowm (option + 
up. down arrow key) and horne/end of document (command + 
up/down arrow key) and the selection equivalents with the shift 
key held down: it s all there, 

DOCLfMENTAllON 

Smile comes with a guided tour in its own file format. It is 
dear and concise, taking about 10-15 minutes to work through. 
More elaborate documentation can be found within the Help 
menu. Smile's documentation makes use of Apple’s Help Viewer 
and turns up as an option within the Help Center (Figure 2). If 
you get totally stuck with Smile you can subscribe to the Smile 
mailing list as described in the help. 


Since being involved in the re-design of ihe id-StudioLab well pages <wwwao.tuddft.nl/id-studiolab/djajiKliningrai/> Tom I ms 
got an even stronger opinion about layout and HTML If you enjoy getting empty mail messages ask him for it with all four 
letter words left out at <J.P.Djajadiningrat@io.tudelft.nl>. 
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Rapid 


Building 

Database 

Applications 

Has 

Never Been 
So Fast! 


Powered By 

OpenBase SQL 


Application 


OPENBASE 

RAD STUDIO' 


Development Envi 




OpenSose RAD studio - o rapid application develop¬ 
ment environment for building Java-enabled database 
applications. 


Easy Drag & Drop Tools, Intuitive drag and 
drop GUI building foals and eveni driven 
QpenScripl dGL accelerate application develop¬ 
ment for software designers and end users alike. 


Instant Deployment, Applications developed 
with R AOs hid to are stored In a central database. 
Users always access the latest software versions 


Scalable Performance. RAOstudio is powered 
by OpenBase $QL r offering high-performance data 
retrieval and transaction control for demanding 
multi-user environments. 


See RAD studio today I 

www.openbase.com/RAD OpenBase 

* . I I l I I t I I A I I | 


n 



Type same vords end click Search, 
or click on underlined word. 

^ Ap ple DVD Pfayer Hel p 
^ Ap pleScript Hel p 
Mac Hel p 

0 QuickTime He lp 

£> Smlle-belR 

* 

Figure Z Smiles help turns up in the Apple Help Center. 

A DiFHiRLNT Philosophy 

If you like you can write scripts straight within a script 
window just its in the Script Editor. However, there is a far more 
powerful way to use Smile. Scripts am be written tn a text 
window and a single line or piece of the code can be executed 
simply by selecting it and pressing enter (For those familiar with 
Mathematics this is somewhat similar to selecting cells and 
pressing enter after each one). This allows much flexibility 
during development as you can execute pierces of script in an 


order of your choosing. It also allows you to leave pieces of 
axle hanging alxxtt without the need to comment them out. 
Once a script works to your satisfaction, you can copy it to a 
script window and save it in the usual variety of formats. 

Apart from script windows and text windows Smile uses a 
worksheet and output windows, making four different types of 
window in total. Figure 3 shows at! four at the same lime. Let's 
have at each of them. 

Worksheet 

This is like a single page Scrapbook particular to Smile. 
Here you can store text and images which you use over and over 
again in different scripts, such as a copyright notice, those code 
samples you can never remember or logos. The result of 
executing a script in a script window is appended to the 
worksheet. The worksheet is saved automatically on quit and 
opened automatically when you start up Smile. 

Text Window 

During script development a text window is like a scratch 
pad. In a text window you can try out pieces of code in any 
order. You can have multiple text windows holding different 
versions of your code. When a piece of script in a text window 
is executed, the result shows up at the bottom of the same 
window. That is, unless you specify an... 
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Output Window 

Selecting a texi window and choosing Output window' from 
the script menu creates a new window and redirects the output 
to that new window* You can also link an output window to a 
script window instead of to a text window. Then the output of 
the script window does noL end up in the worksheet but in the 
output window* 

Script Window 

As mentioned before, you move your script to a script 
window once you wish to save it as an applet* The script 
window distinguishes itself visually by a comments area at the 
top, a coloured background, and a small Uxdbar at the bottom* 
Unlike a text window a script window does not allow execution 
ol code line by line, it only allows you to run a whole script. 



formed the culprit. Another option is to add tell application V to 
every line though this is a somewhat cumbersome solution. 


textV¥lfldow.txt 

tell appJicattofi “Finder" 

I opto the startup disk 

end tell 


Expected *end“ or “end telP but found 
end of script* 


pg 


Figure 4. Stepping into a tell block brings up an error message 

This is where rhe tell command from the edit menu 
comes in (Figure 5k It lets you link a Smile text window to 
a particular application so that commands are directed at that 
application. Choosing the tell command makes a dialog box 
appear in which you can choose an application that is 
running on either the local or a remote machine (Figure 6). 
This turns on a small popup menu in the bottom left corner 
of a text window (Figure 7). Any script commands are now 
directed to the application you just linked to unless you 
specifically ask them to be directed elsewhere. So you no 
longer need to wrap the commands for the linked app in a 
tell block or use a Lei I command on every line* Choosing 
logout from the popup menu breaks the link to the 
application ( Figure 7)* 



Figure 1 The four types oj window in Smite: script window 
Hop left l text window (top rightl output window (bottom right) 
and tmrksheet ('bottom left). 


Decent Debugging 
"Step-by-step 4 debugging 

Let’s go back to executing code in a text window. 
Putting the cursor on a line and pressing enter executes that 
line of code and advances the cursor to the start of the next 
line. So by pressing enter repeatedly you can step through 
the code. 11 even works properly with lines that are broken 
with option-return (->)* Note Itow we almost have step-by- 
step debugging here. Well, almost but not quite* You need to 
watch mu for a few complications. 

If you use a tell block to direct commands to a particular 
application you cant just step into the tell bkx’k: Smile will 
choke on the first line tell application “x" and display an error 
message (Figure 4). It dcx j s work if you select the whole tell 
block and press enter, but of course you ltx)se resolution: if 
things go wrong you don’t know which line within the block 


Cant Undo 


m 


Cut 

MX 

Copy 

mo 

Paste 

9SV 

Clear 

m 

Select alt 

*A 

Had*.* 

3§F 

Find again 

mo 

Enter selection 

36 E 

Find selection 

36H 

Compare 

mK 

Run script 


Check syntax 


Record 


* 

copy translate" 1 


Find definition 

CkWF 

Preferences,,. 


Agents 

► 


Figure 5* Use the tell command to direct AppleScript 
commands to a particular applicaion. 
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Sharon Monplaisir, Olympic fencer and entrepreneur, 
registered her domain name to put her business online 
at register.com- Visit us at www.registencom or can us 
at 1-800-7-WWW-NET, and we’ll help you register your 
domain name right over the phone. 


• com 








Macworld 

Conference & Expo 



January 9 -12,2001 


Register Online 

www.macworldexpo.com 

Call Toll Free 

1-800-645EXP0 

Register by December 11, 2000 for special savings! 

Refer to Priority Code: A-MTCH 

















World-Class exposition! 

Macworld Conference & Expo/San 
Francisco 2001 is a One-Stop-Shop 
offering discounts not found 
anywhere else! 

• Featuring more than 500 
exhibiting companies 

• Thousands of new products, 
software and services 

• Hands-on demonstrations 

• Test-drive new technologies 

• Awards and competitions 

• Prizes, drawings, giveaways 


Special Interest 
Boulevards 

Macworld Conference & Expo offers 
so much for every Mac user! 

Check out the Special Interest 
Boulevards while you are exploring the 
exhibit floor to find and compare hot 
new products for your particular needs. 
Popular areas include: 


Join your friends 

and colleagues in the Mac community 
^ at The Largest IT event 

on the West Coast! 

Cutting-Edge 
Educational Programs! 

Conference sessions for the 
New, Beginning, Intermediate and 
Advanced users! 

Meewortd/Pro features technically in-depth 
presentations and issues-oriented discus¬ 
sions about professional applications of 
Macintosh technology. The Pro conference 
offers the most sophisticated training 
available on Mac networking, digital video, 
art director/creative management practices, 
and Mac systems administrations for 
large organizations. 

Macworld/Users continues to be one of 
the best educational values anywhere. 

The Users conference features industry 
experts offering skill development on 
the most popular Mac-related tools and 
professional development courses 
for users who rely on Apple technology 
to gain a competitive advantage. 



• Digital Multimedia 


• Music and Audio 

• Developer Central 

• Net Innovators 

Be sure tu visit www.macworldexpo.com 
for exciting additions! 


MacBeglnnlngs - San Francisco dehut! 

After great success this July in New York, 
MacBeginnings will make it’s debut 
in San Francisco! These high-energy, 
informative sessions will provide 
first-time attendees, new and beginning 
Mac users a starting point to enter 
the Mac community. MacBeg innings are 
tree and open to Ml registered Macworld 
Conference & Expo attendees! 



Flagship Sponsors 

Macworld 


mncauvcom 


Macworld.com 


Macworld 

Conference & Expo 


www.MmewmMagpe.cttm 



MacwiEK.com 


MacCentraUfem 









Choose a program to lirtlc to: 


Macintoshes 


Programs 


BlAckMaSiC 


Control Strip j&ftsnsion 
Desktop Printing 
FBC indexing Scheduler 
File Sharing Extension 
Finder 

Folder Actions 
Microsoft Word 
Microsoft Word 
Smile 

Time Synchronizer 


□ If I .Cancel..! ft, ll 


figure 6. Specify the application to link to. Here only the local 
host with its processes is shown. 



Figure 7 The tell related popup menu. 


Variable watching 

To further facilitate debugging Smile offers a variable 
watching window. Alter dragging or typing in a variable name 
in this window Smile will show its type and value during 
ex ecu i it in (F igu re 8 J. 


textWmdow2.txt 

MtxtOl 

»ty to 99.99 

set theString to "MacTtcIT 



Figure 8: The variable watcher showing an integer, a real and 
a string. 


Help with AppleScript Syntax 

In addition to the open dictionary command familiar from 
Script Editor, Smile has got some extra features to help you with 
AppleScript syntax problems. First, you can select Find Definition 
from the Edit menu which will try to find the string in Smile's 
dictionary tor if you just linked to another app, that app’s 
dictionary) or in a scripting addition. Second, if you need help 
with the AppleScript syntax of an application ihar you are linked 


to through the tell command you can choose Dictionary from die 
popup menu in the bottom left hand corner (Figure 7). I 
noticed thaL Smile chokes on the dictionary of Palm Desktop, 
while Script Editor has no problems with it Finally, Smile's own 
dictionary' is available under the Apple menu. 

Advanced Stuff 

Portability 

Let’s have a brief look at the somewhat more advanced stuff 
Smile has to offer. One nice feature is that it can assist you in 
writing portable code in which the normal English like 
AppleScript commands are replaced by raw codes. For example, 
il you want to scripi a particular application you may run into 
the problem that a particular user has a localized version of that 
app with a localized name (like SimpleText being called 
SimpdTekst in Dutch) or a version with a slightly different name 
(like BBEdit 5.x instead of lx), ff you want the script to run 
smoothly and prevent a choose application dialog box from 
popping up you can lixik up the application by creator code 
instead of by name and resolve the name of the application at 
runtime* However, this means you cannot use the normal 
English !ike commands as found in the app’s dictionary, you will 
have to use die raw axles. If you first link to a particular 
application through the tell command you can then use the Copy 
Translate feature from the bottom left popup menu to change the 
selected text to raw codes (Figure 7). 

Attachable and factored 

Smile is not only scriprahie and recordable, it also lias those 
mine rare AppleScript virtues: it is attachable, allowing scripts to 
lx* attached to its objects, anil factored. What factored comes 
down to is that when the user chooses a certain command Smile 
sends an Apple event ro itself instructing itself to execute the 
command rather than execute it directly. This ensures that Smile 
reacts in exactly the same way regardless of whether the Apple 
event originated from within or from outside Smile. This 
attachable and factored architecture is particularly powerful in 
combination with... 

Custom interfaces 

You can build your own custom interface for controlling 
Smile and AppleScripts. For example, you can add buttons to 
text window's to create so called Smile sheets and put up your 
own dialog boxes. Option-command clicking a button or dialolg 
opens the attached script. Pretty impressive stuff. Even the 
Variable Watcher is really a Smile sheet. When it comes to 
customization you are pretty much on your own though as the 
documentation concerning thus feature is rather skimpy. 

Interface Critique 

Smiles interface could do with a little tidying up. Especially 
the script menu deserves some attention. At the moment it is a 
bit of a hodge-podge of all kinds of little tidbits provided by 
Sail mage. As this is also the menu in which the user can place 
his own scripts, the structure of this menu can only get worse. 
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Then there is the linking of output .windows to text or script 
windows, To me this seems a pretty essential component of the 
Smile philosophy, yet the command lives under the scripts 
menu. Since choosing output window essentially creates a 
special kind of text window the command would seem to he 
more at home under the hie menu. I also found it a shame that 
[lie format of an output window is stubby and wide below the 
text window to which it is connected. The consequence is that 
any results quickly scroll out of view. I would prefer to have a 
tall Lind narrow output window, positioned to the side of die text 
window, so that older results remain visible and the most is 
made of the available screen real estate* 

The Balance command's name does not do It justice. It 
suggests that the command is limited to indicating or closing 
unbalanced parentheses. However, it is in fad far more powerful 
than that, ft can also suggest syntax, colourize indentation levels 
and assist you in writing tell statements, depending on what part 
of your script is selected [before you activate ii. 

Finally, I find it a bit of a shame that a selection in a read' 
only document is not highlighted. The idea of having scripts 
embedded in read-only documents is quite tempting. It does not 
feel quite right Lhough if you cannot sec what you have selected 
before you press enter. Other applications, such as Tex-Edit Plus, 
do highlight selections within read-only documents. 

Morf Information 

While Smile seems to have gained quite a bit of momentum 
amongst hardcore AppleScript fans, it does not appear to lie 


very well known among the Mac community at large. Here are 
some URLs to help you explore further: 

• http://www.macuser,co.uk/burbulis/printreview.php3?id=35124 (one 
of the few mainstream reviews) 

• hUp://www.AppleSaiptSourcefaookxom/praducts/smil 0 /smile.html ( in- 

depth review of Smile itself) 

• http:y/www.tandb.com au/smile/pgs/SmiSeandScriptEdiTorhtml (Smile 
versus the Script Editor) 

• http://www.tandbxom.au/applescript/editors/ (thorough review of 
available AppleScript editors) 

Conclusion 

They say you can t look a gift horse in the mouth but Smile 
easily stands up to scrutiny. Most of my gripes concern the 
interface which deserves some more attention. All in all this is a 
great addition to the AppleScript scene though. The editing 
features, powerful lookup functions, line-by-line execution and 
variable watching make Smile far superior to Apple’s Script 
Editor, The idea of system wide control from scripts which 
happily live together with styled text and graphics in a single 
document is fascinating. More advanced scr Spiers will appreciate 
the support for portable code, the possibilities to script Smile 
itself and the customizability of its interface through Smile sheets 
and dialogs. The nicest tiling about Smile is probably its gradual 
but seemingly insaturable learning curve: it is easy to pick up 
but it is difficult to imagine exhausting its possibilities. W 
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PROGRAMMER'S 

CHALLENGE 


by Boh Boonstm, Westfard, MA 


What Bills did they Pay ? 

lilts montli we are helping the accounting department of a 
small business with a problem. Our little business is a daily 
newspaper that survives on its advertising revenue. Each day 
they print a newspaper, and each newspaper contains a number 
of ads. Whenever the accounting staff can find the lime, they 
send out invoices to their advertising customers. Sometimes they 
bill daily, sometimes weekly, sometimes irregularly during a 
week or longer period, Mosi of the customers pay promptly, and 
most of them reference the invoice lieing paid along with their 
Payment. That's good, because* our little newspaper has only a 
small accounting staff with no time to reconcile Payments, 

The problem is with a couple of the newspaper’s larger 
customers. These customers don’t always pay promptly, and 
some of them don’t reference the invoice when they pay. To 
make things worse* they sometimes pay part of an invoice, or 
pay multiple invoices with a simple payment. 

Your job is to help sort this all out. The prototype for the 
code you should write is: 

^include "GSUtils*h w 
typedef struct Invoice [ 

DsteTimeftec i nvo 1CeDate: t date on which customer wils invt>iced 7 

long in vo i c e Amoun t: f* m< nmx cusit mult was invoked 7 

lung i nvei c eNumbe r; f reference invi lice number 7 

I Invoice; 


typedef struct PaymenL [ 

DateT Im&Rer payment Cate; f dale payment wits submit led 7 

lorty. payment Amount; f* amount of payment 7 

long paymentNumber; /* reference payment numlxT 7 

I Payment; 


typedef struct Reconci1iaLion 1 
long paymentNumber; 

t reference number of payment I King applied 7 

Ion g 1 n vo i c rN u if.be r; 

r reference number of invoke to which payment is applied, zero if duplicate 7 

long appliedAmount; 

/* amount of referenced payment bring applied lo litis invoice 7 

I Reconciliation: 


long r numlrcr of ret oni'ilbtinn records atmtied 7 Reconr ilePayments 
const Invoice thelnvoieesU, 

P invoices to reconcile,soned by increasing ttatr 7 
cannt Payment thePayttents\), 

t payments to reconcile, sorted by increasing date 7 
Reconciliation thfiRecoricil i.it ion[J. 

t return reconciliation here 7 
lung tiumberOfReconel 1 iutiuriRecords. 

r number of thcHetondiiation itcords praflocated 7 
long MateDolItirJJays f* see problem description */ 


The objective of this Challenge is 10 determine 
which of the Invoices sent to a problematic customer 


have been settled by a sequence of Payments* Your 
ReconcilePayments routine needs to examine 
thelnvoices and UiePayments input arrays and produce 
an array of Reconciliation records. Each Reconciliation 
record must contain the paymenrNuinber of the 
Payment being matched, the invoieeNumber of the 
Invoice being matched* and the amount of the Payment 
being applied to the Invoice* A given paymentNumber 
may appear in multiple Reconciliation records, if the 
Payment reimbursed more than one Invoice. A given 
invoieeN umber may also appear in multiple 
Reconciliation records, if partial payment was provided 
by more than one Payment record. 

There are a few things that you can rely on during 
your reconc iliation. Customers never pay in advance - 
the payment date is never earlier than ihe date(s) of the 
Invoice(s) being paid. Customers might make a partial 
payment, but when they do so they never combine the 
partial payment with payment for any other Invoice. 

Payments might be matched to Invoices in a 
number of ways, so more than one solution might exist. 
We have some constraints* however* that reduce the 
amount of ambiguity. Since we are going to use your 
results to charge interest to our problem customer, and 
we want to be as fair as possible, you must apply 
Payments to the earliest applicable Invoice. If the 
Payment matches a single Invoice exactly, or matches 
the sum of a number of Invoices exactly, you must 
apply the Payment to that (those) Invoiced). II a 
Payment exactly matches the balance of an Invoice that 
has been partially paid by a previous Payment, you 
must apply the Payment to the balance of that Invoice, 
unless some other rule applies (e.g., an earlier Invoice 
that is exactly paid by this Payment). 

To support assessing an interest charge for our 
problematic customers* you need Lo help the accounting 
department by calculating how much this customer is in 
arrears. Specifically* you need to calculate the number of 
dolfar-days the customer is overdue. This is the sum, for 
each unpaid or partially unpaid Invoice, of the unpaid 
balance of the Invoice times the number of days the 
Payment is late. I he unpaid amount is simply the amount 
remaining after your Reconciliation calculations* and the 
number of days late is the difference between die date of 
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the most recent Pay men l and the date of the relevant 
Invoice. The sum of the dolkir-days these Payments are 
late must he returned in the lateDollarDays parameter of 
the Reconcile Pa y me n ts call. 

Keniemlxr tliaL you cannot apply a Payment to more 
than one Invoice unless the Payment exactly totals the 
original amount of those Invoices —you cannot simply apply 
partial Payments to the oldest Invoices to minimize the 
latent illarl>ays value. 

The winner will be the solution that correctly calculates 
the lowest latoDollarDays result. Among tie values, the entry 
with the lowest execution time will l>e the winner 

This will lie a native PowerPC Challenge, using the 
Code Warrior Pro 5 environment. Solutions may lx* axled in 
C, C++, or Pascal. 

This Challenge was suggested by Ernst Munter, 
who adds two Challenge points to his lead for the 
suggestion* Thanks, Ernst! 

One final point, IVe received some letters from people 
who would like to participate in the Challenge, but who find 
tlie problems urn difficult (despite my Ixcst efforts to simplify 
them), or who find out veteran contestants to lx: too 
dominating, fd really like to find a way LhaL new contestants 
could feel comfortable playing, so I'm considering ways to 
revise the prize structure or the points system to make that 
possible, while still being fair to our regular contestants. If 
you have any thoughts along this line, please drop me a 
suggestion at progchalfenge@mactech.com. 

Three Months Ago Winner 

Congratulations to ... - <x>ps, there is no one whom 
we can congratulate for winning the July RAID 5+ 
Challenge, The problem, you might recall, was to design 
a disk input-output system that would survive the loss of 
two disks in the array, A number of folks wrote to say Ural 
the problem was impossible, which must come as a 
surprise to the vendors who marketed solutions to this 
problem. In any case, this is one of those rare months 
when no one submitted a solution. 

Is the problem impossible? Imagine a sequence of 
disks A, B, C, D, and E. Further, imagine that those 
disks are striped as follows: 

AO BO CO DO EG 
Al ft] CUM El 
A2 R2C2 D2F3 
A3B3C3 m E3 
A4B4C4D4K4 

Now, according to the problem statement, the actual data 
capacity of our array only requires N-2 of the available N disks. 
So, to implement protection against the loss of one disk, we can 
imagine calculating parity for block (stripe) n across disks A, B, 
C, D, and E. Cali those parity blocks FI, F2, Then imagine 
calculating another parity block, one for each disk. Call those 
parity blocks FA, PH, ... FE. Then by those parity blocks out 
something like this: 


PB BOCODG PQ 
Al B1C1 PI PA 
A? 52 P2PEE2 
Al P3 PD D3 E3 
P4 PC C4 DA FA 


Notice that the parity blocks are rotated across the available 
disks, hut that the parity requires the capacity of only two disks. 
Note also that there is the equivalent of 3 disks of information 
distributed across the i physical disks. 

So what happens when two disks fail? How do we recover 
a block? Let’s say that disks A and 11 fail, and that we want to 
recover block Al. (Failing these two disks actually represents a 
worst case, since the parity block PB for the failed disk 13 is on 
the other failed disk.) We have ten missing blocks of information 
(6 data blocks and i parity blocks), and we have the following 
parity equations, with the known elements bolded: 

It 50 + CO I DO + FQ - 0 
l: At + Bl + Cl I PI * 0 

3: A2 + B2 + F2 + P2 « 0 

4: A3 + IH + E3 + PI ® 0 

C4 + D4 + E4 + P4 - 0 

6: Al + A2 + A3 + PA - 0 

7: BO 1 Bi + B2 + PB - 0 

0: CO + Cl + C4 + PC * 0 

9: DO + m + D4 I PD - 0 

10: E2 + E3 + E4 4 PE “ 0 
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The first equation allows one to determine BO, die second 
Al+Rt, the third A2+B2, the fourth A3+P3, the filth P4, and die 
eiglith PC. The final two equations are all known quantities and 
do not help* This leaves us with the following: 


1: BO + CO + no + PO - 0 

Z: Ai 4- B) + Cl + PI - 0 (A1 + Bl known) 

3: A2 + R2 + E2 + P2 - 0 (A2 * B2 known) 

4; A3 +■ m + E3 + P3 - 0 (A3 + B known) 

5; C4 +■ 04 + E'* + P'l - 0 

b: Al + A2 + A3 + PA = 0 (Al + A2 + AI known) 

7: BO + Bl + B2 + PB - 0 (Bl + B2 + PB known) 

8: CO + Cl + C4 + PC - 0 

3: DO + D3 + (14 + PD “ 0 

10: E2 + E3 + 14 + P£ “ 0 


This gives us 3 remaining equations and 7 unknowns (Al, 
A2 S A3, BI t B3, P3r and PB). So, it looks like we are short a 
couple of equations to arrive at a unique solution. But we've 
ignored an additional constraint imposed by parity, that x+x=0. 
By enumerating all possible values of these seven remaining 
unknowns, and determining which constraints are satisfied by 
each combination, it turns out that only one combination of 
values satisfies all constraints. So it seems to me that a solution 
ought to be possible. If you think I’ve missed something, please 
let me know and 111 continue the discussion! 

There is also a fair amount of literature on RAID schemes 
beyond RAID 5. If you're interested* you might start out at 
<http://www.pdl.cs.cmu.edu/RAlD/RAlD.htrnl> and take ii from there. 


Top Contestants 

Listed here are the Top Contestants for the Programmers 
Challenge, including everyone who has accumulated 10 or more 
points during the past two years. The numbers below include 
points awarded over the 2 i most recent contests, including 
points earned by this month's entrants. 


Rank 

Name 

Paints 

Rank 

Name 

Points 

1 , 

Mu liter, Ernst 

243 

9 . 

Downs, Andrew 

12 

l 

Saxton, Tom 

106 

ID. 

Jones, Dennis 

12 

3 . 

Maurer, Sebastian 

78 

11 , 

Day, Mark 

m 

-i 

Uieken. Willekc 

65 

12 , 

Duga, Brady 

10 

5 . 

Boring, Randy 

50 

13 . 

Kazekas, Miklos 

to 

6 * 

Shearer. Rob 

47 

14 . 

Murphy, ACC 

10 

7 . 

Taylor Jonathan 

26 

15 . 

Selengut, Jared 

10 

H. 

brown, Pal 

20 

16 . 

Strut it, Joe 

10 


There are three ways to earn points: (D scoring in the top 
5 of any Challenge, (2) being the firs! person to find a bug in a 
published winning solution or (3) being the first person to 
suggest a Challenge that 1 use. The points you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 points 

5lli place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 
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by Jeff elites <onli ne@maciech. com > 


CVS: Version Control is Your Friend 


CVS, the Concurrent Versions System, is the standard 
in version control systems in the Unix world. Traditional 
Mae users may not have used CVS before, and in fact may 
not have used any version control system, but it can save 
you numerous headaches during your development 
projects! and with the arrival of Mac OS X there is no 
longer any excuse—CVS is free and may even come 
preinstalled with your developer look. 

So what is a version control system? In short, it allows 
you to manage and track changes to the files of a project. 
From an operational standpoint, most systems (including 
CVS) arc based on a central repository which contains all 
of the files of your project, and individual developers 
“check out” copies of these files, make changes to their 
local copies, and then 'check in” their changes to the 
central repository, hi the process, die system does three 
basic things for you: it helps coordinate a team of 
developers working on the same project (so that 
programmers don't interfere with other programmers 
working on the same files); it tracks what changes were 
made to what file, when they were made, why they were 
made, and who made them (this helps you identify the 
cause of a newly introduced bug and helps enforce 
developer accountability); and it allows you to revert to a 
version of your project that existed at some previous 
point in time (this allows you to test compatibility with 
previous versions or to undo destabilizing changes). 
Version control isn't a magic bullet or a substitute for 
communication between developers, but it does go a long 
way toward preventing common (and annoying) 
problems. Version control is a must when multiple 
developers are involved in a project, but even a single 
developer working alone will benefit. 

The main advantage that CVS has over most if its 
competitors is that it uses optimistic locking rather than 
pessimistic locking for checked-out file. With pessimistic 
locking, only one developer can check out and modify a 
given file at one time, in order to prevent two users from 
stepping on each others changes in the same file. This 
sounds like a good idea on the surface, but in practice it 
can become a major impediment if users keep files 
checked out for long periods of time, as they would 


naturally do when editing them, or as they may 
accidentally do if they forget to check them backing in 
before leaving for lunch, for the day, or for vacation. 
Ultimately, users will resort to circumventing the system to 
obtain a copy of a "locked” file so that they can get some 
work done, and theyII have to manually reconcile their 
changes with the user who originally checked out the file, 
CVS takes a completely different approach—it doesn't 
lock access to files at a lb Multiple users are free Lo check 
out and work on the same files at the same time, and the 
system takes care of merging changes together as users 
commit their modifications back into the central 
repository. The majority of the time, users don’t actually 
end up editing the same files at the same time (even 
though they may have checked them out, for instance to 
look them over for needed changes), and even when they 
do CVS Is able to merge these changes together 
automatically. In the rare case in which two users have 
both modified the same line of code between check-ins, 
CVS notifies the user of a conflict so that he can resolve it 
manually. This sound like it could cause a mess, but in 
practice ii usually does just what you would have wanted, 
and it only makes you spend your time resolving the rare 
conflict when it actually does occur, rather than causing 
ongoing interruptions in order to ward off potential 
problems that never actually arise. 

CVS has many strong points in addition to the above- 
men tioned "non-locking” behavior. For instance, it is open 
source and licensed under the GPL, and therefore is 
available free of charge. Also, despite its Unix heritage, 
there are GUI-based clients available for the classic Mac 
OS and for Windows, On the other hand, CVS is far from 
perfect—it has been said that it's terrible but it’s the best 
thing around. Many if its flaws are merely nits, I Hit they 
can add up to a noticeable inconvenience. To begin with, 
CVS shares a problem which is unfortunately common 
among open-source projects, namely that it has a 
significant amount of documentation yet it is often difficult 
lo find the exact information you are looking lor. For 
example, a very nice feature of CVS is that it can be 
configure to run over SSH, so that passwords and data are 
encrypted during transmission. It’s hard lo find a complete 
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discussion of this feature, and the setup is such that ids 
easy to think that you've enabled this feature when in fact 
you haven't. (There also doesn’t appear to be a way to 
force the use of SSI I from the server side, t.e. to ensure 
that clients cannot connect insecurely*) 

A second annoyance is the somewhat inconvenient 
handling of directories. CVS fundamentally works on a per- 
directory basis, and in each directory it places a “CVS” 
subdirectory with configuration information. This can 
cause problems if you duplicate a directory and forget to 
remove the duplicate CVS information. Under Mac OS X 
there are many types of “files" which are actually 
directories, and tools which manipulate these need to be 
CVS-aware so that they don’t remove the CVS information 
when saving. Some of these "magic directories* (for 
instance IntcrfaccBuildcrs .nib files) are best thought of as 
opaque binary files, whose contents should not be 
manipulated by merge tools, and there is a ''wrappers’' 
facility which allows you to treat them as such but, 
inexplicably, this feature is not compatible with client- 
server operation* Fortunately, Codefab maintains a 
modified version of CVS which does support both of these 
features, although it’s a shame that the CVS maintained 
don't seem to be interested in merging this back into the 
core distribution. This still doesn’t solve the problem for 
"magic directories" which you don’t want to treat as binary 
(such as KOModdcrs .eomodeld files), but fortunately the 
latest incarnations of Apples developer tools seem lo 
handle the CVS directories correctly. For older version, the 
Omni Group has plug-ins which fix this problem, for both 
EO Modeler and hi ter Face Builder, The directory-centric 
nature of CVS also has the unpleasant side-effect that you 
can't really remove a directory from you project — you can 
only remove the files which it contains. There is a 
workaround in that there is a setting which tells CVS not to 
create empty directories during a checkout, but this has the 
side effect that you can’t place an empty directory under 
version control. (It s rare that you would need to, but it’s 
important to keep in mind in case you ever do.) On a 
related note, you can place binary files (such as images) 
under version control, but you have to go through a bit of 
special configuration to flag them as binary so that CVS 
doesn’t corrupt them, for instance by doing line-ending 
conversion. Often, these types of files do not really need to 
be under version-control per se, but ifs very convenient to 
place them in your repository nonetheless so that you can 
maintain a complete copy of your project, especially in 
web development projects which rend to contain a large 
number of image files. 

Codefab CVS with Wrapper and Client/Server Support 
<http://www.codefab.com/cvs.html> 

Omni Group Plug-ins 

<http://www.omnfgroup.com/community/developer/eoniodeler/> 

<http://www.omnigroup.com/comrTiunity/developer/iriterfacebuiIder/> 


Documentation 

Apple itself uses CVS for some of its internal 
development projects, and in fact Mac OS X Server 
shipped with it pre-installed. In particular it Is used with 
the Darwin project, and there is a page on their Public 
Source site which serves as a good jumping-off poinL to 
find documentation and other information about CVS. 
Here you’ll find a brief introduction to CVS concepts, by 
Apple’s Wilfredo Sanchez. A good next stop is Jim 
Blandy’s "Introduction to CVS", which goes into a bit 
more detail. Next up is “Open Source Development with 
CVS", a book by Karl Fogel. Generously, although this is 
a commercial book, the chapters on CVS itself are 
available for free in a variety of electronic formats. It is 
extensive, well-written, and a pleasant read. Finally, there 
is the core CVS manual, "Version Management with CVS", 
colloquially referred Lo as "the Ccderqvlsr, for the name 
of its original author. It is large and complete, but it may 
not be the best place to start out. Finally, for an account 
of using CVS specifically with web development projects, 
lake a look at "CVS Version Control for Web Site Projects". 

Apple - Open Source - CVS - Docs 
<hTtp://www.publrcsource,apple.com/tools/cvs/docs*html> 

CVS Concepts 

<http://www.publicsource.apple.com/tools/cvs/concepts/> 

Introduction to CVS 

<http://www.cvshome.org/docs/blandy.html> 

Open Source Development with CVS 
<http://cvsbook.red-bean.com/> 

CVS Manual: Version Management with CVS 
<http://www.cvshome.org/docs/manual/index.html> 

CVS Version Control for Web Site Projects 
<http://durak.org/cvswebsites/> 

Much of the core documentation is located on the 
main CVS site, CVShome.org, and it's a good place to look 
for additional information and to download CVS itself, 
despite the somewhat inconvenient organization of the 
site. Their documentation page has links to the most 
important references, including overviews of CVS and of 
version control, and a CVS commands quick reference. 
(0 T Reilly has also just published rheir CVS Pocket 
Reference, if you'd like something a Mule more extensive 
and in printed form.) Also check out the CVS Bubbles site, 
and especially its documentation page, which has links to 
a number of tutorials and to other CVS sites. 

CVS Home - Documentation 
<http://www.cvshome.org/docs/index.html> 

CVS Overviews 

<http://www,cvshome.org/docs/overview.html> 

<http://www,cvshome,org/docs/version,html> 

CVS Quick Reference 
<http://www.cvshome,org/docs/reihtml> 


96 


MA<:Ti:c:it Online 


MacTkcii • October 2000 






CVS Pocket Reference 
<http://www-oreilly.com/c3talog/cvspr/> 
CVS Rubbles 

< http://www. loria. f r/—m o 11 i/cvs-mdex. htm I > 


Alternatives 

If you're a classic Mac OS user* you'll have to run the 
CVS server on a tinix machine, hut there are several 
different clients that you can run: MaeCVS Pro, MacCvs, 
and MacCVSClient. Despite their similar names, these are 
separate applications. The first of these, MaeCVS Pro, is 
sponsored by the Mozilla project, and appears to he the 
most current version. 

MaeCVS Pro 

<http://www.maccvs.org/> 

MacCvs 

<http://www.wincvs.org/> 

MacCVSClient 

<http://www.glink-net.hk/'-jb/MacCVSClien t/> 

lender Mac OS X, CVS should work “out of the box" 
thanks to the 13SD layer. If you don't like the command¬ 
line version (which really is quite easy to use), there is a 
GUT from end, CVL (Concurrent Versions Librarian) by 
Sen:te, CVL works on top of the standard CVS rather than 
replacing it. This is nice, because it should be forward- 
compatible, and it also means dial you can resort to Llic 


command-line version if there is some additional feature 
you need to use which CVL doesn’t support, and you can 
do this without worrying that you might “mess up* any of 
the locally stored administrative information. 

Concurrent Versions Librarian 

<http://www.sente.ch/software/cvl/> 

Finally, if CVS isn’t to your liking after you’ve tried it 
out, there are several alternatives, and you might want to 
use one of l be commercial systems. For the classic Mac 
OS there is VOODOO (Versions of Outdated Documents 
Organized Orthogonally). If you need support for 
multiple platforms, take a look at Perforce, which seems 
to be well liked and Ls available for a wide range of 
operating systems, although there don’t appear to he any 
GUT based clients for it. (While visiting Perforce 3 s site you 
might also want to check out JAM, which is a build system 
designed as an alternative to make, and which is used as 
the build system under Mae OS X\s ProjecLRuilderJ 

VOODOO 

<http://www.uni5oftwareplus.com/products/procIucts.htnit> 

Perforce 

<http://www.perforce.com/> 
lam - Make{1) Redux 

<http://www,perforcexom/jam/jam.html> 
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Copyleft or Copyright 


Into the new paradigm 


The world of publishing is about to change in a very 
dramatic fashion. 

Publishers and distributors are alx>ut to find that die proverbial 
cat that s Ixron hiding in die WWW has just escaped its bag. The 
form ii lakes is called the Tree Digital library” (FDD. 

Free at the FDL does not necessarily mean without cost, 
it defines free in the sense of “Freedoms For example, the 
open software movement gives to humanity their source 
code, the code is free as opposed to being an intellectual 
property right belonging to a single entity. This means the 
information is allowed to evolve and be shared for die 
benefit of all humanity. This concept of information being 
the intellectual property of all humanity can be termed 
“Copyleft", 

The legal mechanism called "copyleft* assures: 

• The author will be perpetually acknowledged in any use 
of her or his creative Works 

• The Works will not become private properly 

• Tile Works remain available to inspire and be built upon 
by other creative minds 

The creators of the FDL have two simple goals: 

1. Attract and expand a knowledge base of Free Information; 

The people who created the FDL make very dear a few 
points about the their creation: 

1. lhe project has no owners, stockholders, officers, or managers 

only volunteers, donors, participants, and users. 

2. 1l is “owned” by its users and exists solely in sendee to them. 

3. It provides zero-cost services and “owns" absolutely nothing. 
■h h was bull?, will change, and be operated entirely through 

volunteered time and effort, donated services, and 
financial support (if necessary). 


3. It has been scrupulously constructed as a “human 
experiment” with no restraints on direction, speed, or 
content. It will "go 11 wherever and “carry” whatever Free 
Information is determined by its users. 

Here’s how It works. Creators ol digital information use the FDL 
library of links to place their link to their information, providing the 
ability id freely self-publish. If Creators of digital work wish to 
commercially distribute their product lor commercial compensation 
then they go through a different process. 

Tile Commercial Distribution and Compensation process is one 
of die most unique aspects to what the FDL represents, Ar first glance 
the compensation plan looks akin to a chain letter, the differences 
Ixang built in authentication, tracking ability, and verification controls 
for the distribution process. For example, if someone orders the 
offered product and docs not pay ynu or information you ordered 
from a distributor docs not arrive, then you would repot them on 
the appropriate Peer Review site. If someone is selling information 
that is valueless (at least in your opinion) then you can review their 
work on the Authors Peer Review page. Since you have many 
“letters” to choose from that you might like to distribute, it’s up to 
you to choose what you think Is worthwhile. If you think none of 
r he 1 1 1 rren E D isE ri but ion Not it :es is va Ilia 1 1 le Lhe n pix wide you r c >wn 
creative works that can lie distributed. 

'lhe Distribution Notice offers four articles by four distributor 
st >u rt :es. Digital ly se ! f-pi 1 1 >1 jstlet 1 i nit srm:llion is attadted at each of l\ te 
four levels that ate sold for five dollars each. The author and the 
article never change positions, only the current distributors change 
when a new person chooses to participate because they will put their 
name and payment instructions in position one while moving 
everyone else up one level, Each work is $5.00 so your total cost to 
own and redistribute all four prcxlucts is a one time $20.00 outlay. 

Tiie sources and titles will look something like this when 
you receive the e-mail offering the products and your 
Opportunity to become a distributor: 

Source 1 Position I: Mary x - Article in position 1 title and Author 
Payment details (Paypal account or address) 


Stephen Fantl is the Executive Director of SAFE., a sustainable farming and organic agricultural Non-profit working on sustainable community 
models. Funding for the S,A.KE, project will come from clisiribution by volunteers of their creative works through the FDL. 
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Source 2 Position 2: BoHry x - Article in jxxsition 2 title anti Author 
Payment details (Pay pa I account or address) 

Source 3 Positk*n 3: Jane x - Anide in position 3 Nile and Author 
Payment details (Paypal account or address) 

Source 4 Position 4: David x - Article in position 4 title and Author 
Payment details (Paypal account or address) 

Here is a Hypothetical situation that shows how the process works 

1. Si >urce 1 1 1 sends e-mail introdudug the copylefted articles ft ir sale 
and distribution to you, 

2. Upon recognizing the apparent value of the Works offered, 
you decide to order all four and send a $5 payment lo each 
Source listed on the notice (the four authors or distributors 
through whom die notice has passed). Additionally, you 
must reply to Source 1 to request the Delivery Instructions 
for the entire set of Works. 

3. Upon receiving your e-mail request Source 1 responds to your 
e-mail address with the Delivery Instructions for the set of Works 
(shown as Works 1, 2, 3, and 4). By taking ownership of the sea 
of Works, you have agreed to make tile S3 payments to each of 
lire four Sources (the four Sources listed on the Notice to which 
you are responding) in exchange for their efforts in the creation 
and distribution of the set of Works, 

4. After initialing payment and following the Delivery 
Instructions, you now own the four copylefted Works. 
You resell in the same way in which they came to you 
(becoming yourself a new Source 1). By applying the 
same methodology in which you received the Works, you 
e-mail the same Delivery Instructions you received, in 
Step 3. lo the others who responded to you're Notice. 

In a nutshell by purchasing, tints owning copylefted Works, 
you have also received permission to sell them to others in the same 
manner you purchased them should you chcxwe to do so. This 
model when coupled with verification anil authenticity controls is a 
very effective and equitable tool for remunerating authors and 
participants who are interested in making money distributing free 
Information, Fven if you are not the author you can purchase a 
notice from someone like myself pay a total of twenty dollars, five 
paid out to each four distributors, and ilien you would be returned 
an appropriate sum leased on your efforts. Look at the math of this 
logarithmic distribution system. 

Let's assume for our first example that Ixtween everyone there 
is an average of ten people per person with whom they distribute 
the information to who will do the same. 

1st level: your 10 memliera each pay you and the other three 
people on the list $5.00 

($5 x 103 - $50 

2nd level: 10 memlxrs from each of those 10 

($5 x 100) = $500 

3rd level 10 memlxrs from each of those KM) 

($5 x 1,000) - $5,000 

4th level: 10 memlxTi from each of those I S (XX> 

(55 x 10,000) = $50,000 


Remember that this assumes the people who participate recruit 
10 people each. Ginstder what luppcns if they got 20 people to 
participate! It Is common in the MLM industry for people to Iiave 
hundreds of participants in their personal networks. However. 
1)ecause tlie width of your network is entirely self-deiermined, lets 
look at other network widths of 2 and 6 progressions. 

2-pcrson progression: 1st Level = $10 - 2nd level = $20 - 3rd 
level = $40 - 4th Level = $80 for a total of $150.00 

6-person progression: 1st level = $30 - 2nd level = $180 - 3rd 
Level - $1,080 - 4th Level - $6>480 for a total of $7,770 

The potential that this type of distribution and compensation 
package offers is tally staggering. It Is u Win/WirVWin scenario for 
the Authors, distributors, and even the public as a whole since 
knowledge and information are- being freely (Copylefted) circulated. 
Because the information you can purchase and resell is dipped from 
the endless stream of creative input flowing into die Free Digital 
Lihraty, you ran do it all again with entirely fresh information, That 
is, you can promote new iiilonnation to your first generation Referral 
Group who originally purchased from you die first time round; as 
well as to any additional participants you attract into your 
organization* and each of them am repeal exactly the same thing 
with their respective first generation Referral Groups. 

Do you see die power and potential once you have your first 
generation? When you get a new opportunity you will simply hit one 
button to offer it to everyone who made money widi you previously, 
if someone you know did not succeed, then buy a notice from them 
and send iL to your network, the person you bought it from (who 
didn't collect much) will now k assured to collect almosL as much 
as you. How much you are making is up to you. To help widi that 
I Iiave links at the bottom of the page tliat w ill take you to places 
you tan advertise tin die Internet for free, follow these links and you 
should do phenomenal. 

Although the Free Digital library may be the first to employ tills 
method of controlled logarithmic marketing, it certainly will not be 
the last, ihe site will lx active by August 18. 2000 and will Iiave at 
least two notices available lor distribution. Implementing these 
distribution & publishing concept signals the Ixginning of the end 
for competitive publishing and distribution practices. Remember that 
you can publish digital an. digital music, software, creative writings, 
and even digital video through the FDL and begin to reap the 
economic benefits of your creative and energetic output. And why 
shouldn’t you? I welcome your feedback. 

If you find this concept interesting, you can visit the FDL at 
< http ://wvwv, freed! g i ta 11 i b rary, com >, <http://www.freedigitallfbrary.net>, or 
<http://www.freedigitallihrary.org>,. If you have questions or you 
would like to receive the first and most immediately available 
distribution notice, which is only .sent out by individuals, never 
by the FDL itself, please e-mail: < m a i I to: freed i g i lal i nfo@lycos. com > 
with the Subject: "Distribute". 

1 lave fun publishing! Efl 
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Compare the best Mac products 
at the best prices. 



MacBuy.com, The Macworld PriceFinder, reviews and compares out-the-door 
prices of available Macintosh products from a wide array of online vendors. 
You'll quickly find the best product for your needs, and you'll also find the 
best price. Shop and compare computers, new and upgrade software, 
printers and more - it's all there. 

The Macworld PriceFinder is your comprehensive resource for choosing 
the best Macintosh products, getting the lowest prices and buying with 
confidence from the vendor of your choice. 

mncBuvcom 

The Macworld PriceFinder 
www.macbuy.com 

Muc ] h uMilling LH-. Maewwld.eam aiv umkmvris of Mac PubtiKhin^ Mnsimosh i* ct registered trademark ftf Apple Cumputef. Ins 








OPINION 


By ttvne Hoffman. Contributing Editor 


Cable Modem Guide 


Welcome 

Cable modem access has finally 
reached mass proportions. If you don't 
liave it, you will Mx>n, High speed 
Internet atxxss is almost required these 
days to access all the Flash, Shockwave, 
QuickTime, and other useless crap 
posted by many web sites. The 
following notes are meant to help you 
wade through the cable abyss, so Lhiti 
you are not caught unawares. 

1. First, Unci exit which company is 
tile cable tv provider in your town — 
because that’s about your only choice. 
These companies have a monopoly in 
any town they cover 

2, IF you happen to lx* one of the 
very T lucky few who has more than one 
cable provider —Call ilieir tech support 
line, or I ni ling, or almost any number 
associated with the cable company - 
listen carefully to their hold music. As 
most of your communication with your 
cable provider will lx waiting on hold 
you might as well pick a company who 
plays music you like, 

(Recently my ears were assaulted 
with classical music, REALLY loud 
classical music from Mediaone, now 
Roadninner, now AT & T When I called 
RCN though, I was greeted with "Hold 
on i"m Gutting” by the Temptation^?) 
and "Wait a Minute Mr Postman* by the 
Beatles — obviously RCN has a better 


sense of humor! I was expecting Stevie Wonders Don't You 
Worry Bout a Tiling next.) 

3, If you arc* lucky enough to have more than one cable 
service provider, when you call, see what their wait time on the 
phone is — I guarantee you won't need a stop watch for this 
one. Pick the company that puis you on hold for less hours. 

4, Mediaone (AT&T) advertises broad hind service — 
what tilery really mean is when you buy a head .set so you can 
stay on hold all day and still gel something done; they mean 
buy one with a wide head strap, so you'll lie more comfortable, 
while you wait ,« and wail ... and wait... 

5, If you ever really need tech support lx prepared to be 
the victim. First, they will fell you. you're on a Macintosh, 
which of course they su]Jport; but tlien they tell you to hold 
ihe left mouse button, and ask if Windows Ls running. Second, 
iliey will blame your OS, doesn't mailer what version you’re 
running — its your fault! 

6, Once they’ve eslablished that you're on a Mac, and that the 
OS is ok. then they'll blame your old version of TCP/IP (which of 
course is the newest version) or Open Transport — doesn’t matter 
if you've been working line for 2 years with your set up - its still 
your fault or !x*tter yet. Apple’s programmers. Now, the blame is 
slowing being spread to a whole slew of jxople! 

7, After holding for a hour to get lech support, and 
rebtxMing your machines ten limes and discovering that its all 
your fault, and your patience is running ihin — you make ihcm 
O IECK iheir stuff.,, and yes, only to find out their .service is in 
fact down, not only in your town; but in the five contiguous 
towns t(H). "Fltey just hadn't figured that out yet. (See the 
support call at the end of this rant.) 


llene Hoffman is a Contributing Editor at MacTech magazine. Sometimes she jutf can t lake it anymore. She is also the 
Adminishator at MacEixJccom Forums and has worked with many cximmuniiy-based web sites. Comments on this article can 
lx* mailed lo: iJcneh® mac. coin. 
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9. Now, that you’re completely frustrated with your cable 
provider and they have a land lock on your town, you might 
decide to explore DSL DSL provides a whole not her set oi 
small nightmares — smiting with their request you buy their 
modem. They want you to buy their modem as soon as you 
order the service, hut you can't use that modem until the 
service Is activated — which in the Boston area is a g<xxl 
month wait. So, its hurry up and wait, but pay first. 

10, The best thing is once you are connected you will 
have speedy Internet access ... for atxaut 10 minutes. Due to 
the phone lines in your area, your speed will be alxjut half 
what is advertised, so you can expea slightly faster 
downloads than using that 2400 baud modem you have 
a Electing dust on your floor. 

Ah... life in the fast lane... 

A Recent Summary oi- a Support Call I Made 

Dial the cable company. 

Listen to the message that their options have changed and to choose my 
opt km tan: hilly. 

Type in my phone number. when requested and press l. 

listen die message that their options have dianged and to choose my 

option carefully. 

Type in my phone number, when requested anti press 1. 
l isten the message that their options have changed and to choose my 
option carefully. 

Type in my phone number when requested and press I. 

Hang up, 

Duil. the cable company 

Listen tile message that their options have changed and to choose my 
op tion card’ll I !y 

Type in my phone number, when requested and press 1 .(repeat 3 more 
times) 

lie pm on hold 

A half hour later, after being told 13 rimes ‘We appreciate your patience, 
please continue holding, your call is important 10 us*” a person answers 
the phone* and asks for your phone number. 

Support: "What is your problem?" 

Me: “My cable modem is nor working," 

Support: “Is this for your television set?” 

Me: “No, l don’t have a cable modem on my TV, it's for the Internet." 
Support:“What is the problem w-ith your cable modem?” 

Me: “My modem Is unstable'* 

Support:“Is is going to fall over? Is it on a desk?' 

Me (holding my breath) “No, my modem lights are blinking, 
and unstable,'* 

Support ^What’s your modem look like?” 

Me: “Well, its this black rectangular box,., — look 1 can t connect to the 
Net, can I speak with someone else?” 

Support:" 1 Oil,you need Internet access support.'* 

Me: wait on hold while Internet access support is 
flown in from l*aragttay. 

Support:“Hello, can J have the phone number you are calling in from?" 
Me: Give my phone number, address, social sceuriiy number, mother’s 
maiden name, and medical history of every dog I’ve ever owned. 
Support:"What seems to be the problem? 1 ' 

Me: "My modem lights are blinking, and unstable," 

Support: “Have you tried accessing our help pages on the Internet?" 

Me: (chewing on my keyboard...) “Uni, no r 1 can't get ON the Internet A 
Support: “Ok, first unplug the modem 7 


Me: Scrunch into a tiny little ball, squeeze under the desk and crawl 2 
feet in the dark to reach my modem. Unplug modem, and hit my head 
while returning to the phone. 

Support:“t)k. now wc must wait." (Note: (hey have a egg-timer which 
they use to time the amount of time the modem is disconnected.) 

Me: Wait. 

Me: Wait. Two or so minutes later... 

Support “Ok, plug it back in.’ 

Me: Repeat contortions listed above 
Support: “Ok, Now- what’s the modem doing?" 

Me: “Blinking.” 

Support: “Ok, let me cheek your line. Oh, there’s definitely a problem. 

I can’t ping your modem,” 

Me; “Have you tried checking the area to see if the service is down?” 
Support: “Oh. we d know if there was a problem with the service 
in your area,” 

Me “Might I suggest you double-check?’ 

Support:“Be right back," ,. 

Support:'Oh* your node in your town is down, there's no 
service right now 1 ," 

Me: DUI1. 

Support: “Gee, thanks for calling, I don't know why wc didn't know the 
service was down. Well send someone out and gel the problem taken 
care of. Usually we know w'heo a service In a town is down." 

(Note: this is the fourth time this year their service was out and 
they didn't know it.) 

Four hours later my mtxlem service was hac k up. 

Disci aimer 

Any resemblance to any services living or dead is 
purely coincidental* I only report em as I see cm. Your 
mileage may vary, EQ 


USHStuff 

1-88-USB USB US 

-or- (1-888-728-7287) 

Worldwide Distributors of USB 
and FireWire Parts, 
Peripherals and Accessories 

Hey Developers: 

http://www.u»bstuff.com/dovelopers.html 

1-877-4 HOTWIRe 

-or- 1-877-446-8947 

fireWCrt&tuff 
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HOW DO YOU SAY 

Superb 




When you think of Superb, you think of unusually high quality. Like a superb wine, for example. Majestic. 
Rich. Luxurious. Superior. ■ SuSE Linux is all that. And more. More experience. More adaptability. More 
applications—over 1500. ■ More power to you. And more freedom, too. ■ No wonder more than 50,000 
enterprises worldwide bank on its superb open source solutions. Making SuSE the international Linux leader 
setting a higher standard for excellence, simplicity and support. ■ Even the price is superb. ■ So, how do you 
say superb in Linux? SuSE. It's a lesson well learned. 

www.SuSE.com 


Versions for Intel, Alpha, and PowerPC 


The freedom to change. 
The power to change the Linux world. 



C 2000 SuSE. AN rights reserved- SuSE, and StiSC tout) LiwferiMto of SuSE GmbH Ottwu nans* may he trademarks of tfKM respect we owners. 
















Time matters. 

The fate of the company is in your hands. 

Every second counts when you're compering at Internet speed. 
And the faster your Web application is developed, deployed and 
maintained, the faster yuur comped don will drop out of sight. 

Ihc solution? Use Pervasive Softwares Tango 2000 to develop 
your ideas with double die speed of any odier development software. 

* Visually develop applications on Mac, and deploy on 
Mac, Windows, Linux and Solaris 

* Advanced XMt. support 

* Connect direedy to Hlemaker or any ODBC database 

* Extend applications with JavaBeans 

* I ligh performance Tango server scales with duster support 


Give yoiuself the same competitive edge that dango has 
given leading companies like Apple Computer*, thcglobexom" 
and Harbor freight Tools "’. 

Download your Free Tango Demo today! 

Crab the rime-saving advantages oflango 2000 absolutely 
f REE. Visit our Web site anti download our FREE fully funcrional 
Tango 2000 demo. Or call us now to get vour demo on CD. 

www.pervasive.com/speed or 1-800-287-4383 

Hurry! This offer ends soon. 


PERVASIVE 

\SOFTWARE 

The Freedom lo Create Applications 
for Everyone, Eve r 

Appte Computer re a registered iraaernaih ot /Hppte Computer, Inc.. 1fw0obe.wm is e inrctenwj* of itwglobe.Kjm. trwi , Harbor Fr&rght Toe* m a trademark m Houbot Freight Tdoikc- 












